From 68848aa550bed6b67626be5d0ac4a77838d1252d Mon Sep 17 00:00:00 2001
From: Stephen Sawchuk <sawchuk@gmail.com>
Date: Thu, 2 Oct 2014 09:44:13 -0400
Subject: [PATCH] pubsub refactor

---
 docs/components/docs/docs-services.js |   20 +
 docs/components/docs/docs-values.js   |   50 ++
 docs/components/docs/docs.html        |   25 +-
 docs/components/docs/docs.js          |  200 +++--
 docs/index.html                       |    3 +
 docs/lib/semver.js                    | 1098 +++++++++++++++++++++++++
 lib/common/util.js                    |    3 +
 lib/index.js                          |   29 +-
 lib/pubsub/index.js                   |  534 +++++-------
 lib/pubsub/subscription.js            |  327 ++++++++
 lib/pubsub/topic.js                   |  270 ++++++
 npm-debug.log                         |   33 +
 package.json                          |    8 +-
 regression/pubsub.js                  |  200 +++--
 scripts/docs.sh                       |   27 +
 test/pubsub/index.js                  |  219 +++--
 test/pubsub/subscription.js           |  430 ++++++++++
 test/pubsub/topic.js                  |  341 ++++++++
 18 files changed, 3192 insertions(+), 625 deletions(-)
 create mode 100644 docs/components/docs/docs-services.js
 create mode 100644 docs/components/docs/docs-values.js
 create mode 100644 docs/lib/semver.js
 create mode 100644 lib/pubsub/subscription.js
 create mode 100644 lib/pubsub/topic.js
 create mode 100644 npm-debug.log
 create mode 100755 scripts/docs.sh
 create mode 100644 test/pubsub/subscription.js
 create mode 100644 test/pubsub/topic.js

diff --git a/docs/components/docs/docs-services.js b/docs/components/docs/docs-services.js
new file mode 100644
index 000000000000..6df728e744e0
--- /dev/null
+++ b/docs/components/docs/docs-services.js
@@ -0,0 +1,20 @@
+angular.module('gcloud.docs')
+  .factory('getLinks', function(pages, versions) {
+    return function(version) {
+      var baseUrl = '#/docs/' + version;
+      var VERSIONS = pages.VERSIONS;
+      if (!version || version === 'master') {
+        var versions = Object.keys(VERSIONS);
+        match = versions[versions.length - 1];
+      } else {
+        match = Object.keys(VERSIONS).filter(semver.satisfies.bind(null, version))[0];
+      }
+      return VERSIONS[match]
+        .map(function(module) {
+          if (pages[module]._url) {
+            pages[module].url = pages[module]._url.replace('{baseUrl}', baseUrl);
+          }
+          return pages[module];
+        });
+    };
+  });
diff --git a/docs/components/docs/docs-values.js b/docs/components/docs/docs-values.js
new file mode 100644
index 000000000000..8eda76b49ba3
--- /dev/null
+++ b/docs/components/docs/docs-values.js
@@ -0,0 +1,50 @@
+angular.module('gcloud.docs')
+  .value('pages', {
+    gcloud: {
+      title: 'gcloud',
+      _url: '{baseUrl}'
+    },
+
+    datastore: {
+      title: 'Datastore',
+      _url: '{baseUrl}/datastore',
+      pages: [
+        {
+          title: 'Dataset',
+          url: '/dataset'
+        },
+        {
+          title: 'Query',
+          url: '/query'
+        }
+      ]
+    },
+
+    pubsub: {
+      title: 'PubSub',
+      _url: '{baseUrl}/pubsub',
+      pages: [
+        {
+          title: 'Topic',
+          url: '/topic'
+        },
+        {
+          title: 'Subscription',
+          url: '/subscription'
+        }
+      ]
+    },
+
+    storage: {
+      title: 'Storage',
+      _url: '{baseUrl}/storage'
+    },
+
+    VERSIONS: {
+      // Give a version with/without a comparator, anything semver:
+      //   https://github.com/npm/node-semver#versions
+      // List should be in ascending order.
+      '<=0.7.1': ['gcloud', 'datastore', 'storage'],
+      '>0.7.1': ['gcloud', 'datastore', 'pubsub', 'storage']
+    }
+  });
diff --git a/docs/components/docs/docs.html b/docs/components/docs/docs.html
index be0e1e0d3f5a..7cd950d59738 100644
--- a/docs/components/docs/docs.html
+++ b/docs/components/docs/docs.html
@@ -73,6 +73,21 @@ <h3>Datastore Overview</h3>
         </p>
       </article>
 
+      <article ng-if="isActiveDoc('pubsub')">
+        <h3>Pub/Sub Overview</h3>
+        <p>
+          The <code>gcloud.pubsub</code> method will return a <code>pubsub</code> object, allowing you to create topics, publish messages, subscribe to topics, and more. See the <a href="https://developers.google.com/pubsub/overview">Google Cloud Pub/Sub overview</a> for more information.
+        </p>
+        <div hljs>
+var pubsub = gcloud.pubsub({
+  projectId: 'myProject',
+  keyFilename: '/path/to/keyfile.json'
+});</div>
+        <p>
+          See the examples below, which demonstrate everything from creating a topic to subscribing to messages on a topic.
+        </p>
+      </article>
+
       <article ng-if="isActiveDoc('storage')">
         <h3>Storage Overview</h3>
         <p>
@@ -98,8 +113,7 @@ <h2 ng-if="method.name[0].toUpperCase() === method.name[0]">
           ng-if="method.name[0].toUpperCase() !== method.name[0]">
           <a
             class="permalink"
-            ng-if="!noPermalink"
-            ng-href="{{activeUrl + '/' + method.name}}">#</a>
+            ng-href="{{activeUrl + '?method=' + method.name}}">#</a>
           {{method.name}}
         </h3>
         <p ng-if="method.description" ng-bind-html="method.description"></p>
@@ -118,9 +132,8 @@ <h4 ng-show="method.params">Parameters</h4>
         <h4 ng-show="method.returns">Returns</h4>
         <p ng-show="method.returns" ng-bind-html="method.returns"></p>
         <h4 ng-show="method.example">Example</h4>
-        <div ng-repeat-end
-          ng-show="method.example"
-          hljs source="method.example" language="js"></div>
+        <div docs-example ng-repeat-end
+          ng-show="method.example" ng-bind-html="method.example"></div>
         <hr ng-if="$index < methods.length - 1">
       </article>
     </article>
@@ -135,7 +148,7 @@ <h4 ng-show="method.example">Example</h4>
 
   <nav class="side-nav">
     <ul class="page-sections" ng-show="showReference">
-      <li ng-repeat="page in pages">
+      <li ng-repeat="page in links">
         <a
           ng-class="{ current: isActiveUrl(page.url) }"
           ng-href="{{page.url}}">
diff --git a/docs/components/docs/docs.js b/docs/components/docs/docs.js
index da018a448427..10d93ff15d0d 100644
--- a/docs/components/docs/docs.js
+++ b/docs/components/docs/docs.js
@@ -4,14 +4,41 @@ angular
     'use strict';
 
     function filterDocJson($sce, version) {
-      // Transform JSON response to remove extraneous objects, such as copyright
-      // notices & use strict directives.
+      // Transform JSON response to remove extraneous objects.
       function formatHtml(str) {
         return str
             .replace(/\s+/g, ' ')
             .replace(/<br *\/*>/g, ' ')
             .replace(/`([^`]*)`/g, '<code>$1</code>');
       }
+      function formatComments(str) {
+        var matched = 0;
+        var paragraphComments = /\/\/-+((\n|\r|.)*?(\/\/-))/g;
+
+        if (!paragraphComments.test(str)) {
+          return '<div hljs language="javascript">' + str + '</div>';
+        }
+
+        str = str.replace(paragraphComments, function(match, block) {
+          return '' +
+              (++matched > 1 ? '</div>' : '') +
+              '<p>' +
+              formatHtml(detectLinks(detectModules(
+                block.trim()
+                  .replace(/\/\/-*\s*/g, '\n')
+                  .replace(/\n\n/g, '\n')
+                  .replace(/(\w)\n(\w)/g, '$1 $2')
+                  .replace(/\n\n/g, '</p><p>')
+              ))) +
+              '</p>' +
+              '<div hljs language="javascript">';
+        });
+
+        str = str.replace(/(<div[^>]*>)\n+/g, '$1\n');
+        str = str.replace(/\n<\/div>/g, '</div>');
+
+        return str;
+      }
       function detectLinks(str) {
         var regex = {
           withCode: /{@linkcode <a href="([^\"]*)">([^<]*)<\/a>/g,
@@ -42,13 +69,23 @@ angular
         };
         var a = document.createElement('a');
         return str.replace(regex.see, function(match, module) {
-          a.href = '#/docs/' + version + '/' + module;
+          var path = module;
+          if (path.indexOf('#') > -1) {
+            path = path.split('#').map(function(part, index, parts) {
+              if (index < parts.length - 1) {
+                return part + '/';
+              } else {
+                return '?method=' + part;
+              }
+            }).join('');
+          }
+          a.href = '#/docs/' + version + '/' + path;
           a.innerText = module;
           return a.outerHTML;
         });
       }
       function reduceModules(acc, type, index, types) {
-        var CUSTOM_TYPES = ['query', 'dataset'];
+        var CUSTOM_TYPES = ['query', 'dataset', 'topic', 'subscription'];
         if (CUSTOM_TYPES.indexOf(type.toLowerCase()) > -1) {
           if (types[index - 1]) {
             type = types[index - 1] + '/' + type;
@@ -88,13 +125,13 @@ angular
                 })
                 .map(function(tag) {
                   return $sce.trustAsHtml(
-                      tag.types.reduceRight(reduceModules, [])[0])
+                      tag.types.reduceRight(reduceModules, [])[0]);
                 })[0],
               example: obj.tags.filter(function(tag) {
-                  return tag.type === 'example'
+                  return tag.type === 'example';
                 })
                 .map(function(tag) {
-                  return tag.string;
+                  return $sce.trustAsHtml(formatComments(tag.string));
                 })[0]
             };
           })
@@ -104,24 +141,39 @@ angular
       };
     }
 
-    function setMethod($location, methodName, version) {
+    function setSingleMethod(method) {
       return function(methods) {
-        var methodExists = methods.some(function(methodObj) {
-          return methodName === methodObj.name;
-        });
-        if (methodExists) {
-          methods.singleMethod = methodName;
-          return methods;
-        } else {
-          $location.path('/docs/' + version + '/' + module + '/' + cl);
+        if (method && methods.some(function(methodObj) {
+          return methodObj.name === method;
+        })) {
+          methods.singleMethod = method;
         }
+        return methods;
       };
     }
 
-    var MODULE_TO_CLASSES = {
-      datastore: ['dataset', 'query'],
-      storage: []
-    };
+    function getMethods($http, $route, $sce, $location) {
+      var version = $route.current.params.version;
+      var module = $route.current.params.module;
+      var cl = $route.current.params.class;
+      var path = ['json', version];
+      if (!module && !cl) {
+        path.push('index.json');
+      } else if (module && !cl) {
+        path.push(module);
+        path.push('index.json');
+      } else if (module && cl) {
+        path.push(module);
+        path.push(cl + '.json');
+      }
+      return $http.get(path.join('/'))
+          .then(filterDocJson($sce, version))
+          .then(setSingleMethod($location.search().method));
+    }
+
+    function getLinks($route, getLinks) {
+      return getLinks($route.current.params.version);
+    }
 
     $routeProvider
       .when('/docs', {
@@ -134,72 +186,23 @@ angular
       .when('/docs/:version', {
         controller: 'DocsCtrl',
         templateUrl: 'components/docs/docs.html',
-        resolve: {
-          methods: function($http, $route, $sce) {
-            var version = $route.current.params.version;
-            return $http.get('json/' + version + '/index.json')
-                .then(filterDocJson($sce, version))
-                .then(function(methods) {
-                  // Prevent displaying permalinks.
-                  // ** Can remove when PubSub api is documented **
-                  methods.noPermalink = true;
-                  return methods;
-                });
-          }
-        }
+        resolve: { methods: getMethods, links: getLinks }
       })
       .when('/docs/:version/:module', {
         controller: 'DocsCtrl',
         templateUrl: 'components/docs/docs.html',
-        resolve: {
-          methods: function($http, $route, $sce) {
-            var version = $route.current.params.version;
-            var module = $route.current.params.module;
-            return $http.get('json/' + version + '/' + module + '/index.json')
-                .then(filterDocJson($sce, version));
-          }
-        }
+        resolve: { methods: getMethods, links: getLinks }
       })
       .when('/docs/:version/:module/:class', {
         controller: 'DocsCtrl',
         templateUrl: 'components/docs/docs.html',
-        resolve: {
-          methods: function($q, $http, $route, $sce, $location) {
-            var version = $route.current.params.version;
-            var module = $route.current.params.module;
-            var cl = $route.current.params.class;
-            if (MODULE_TO_CLASSES[module].length > 0) {
-              return $http
-                  .get('json/' + version + '/' + module + '/' + cl + '.json')
-                  .then(filterDocJson($sce, version));
-            } else {
-              // This is not a class, this is the name of a method.
-              var method = cl;
-              return $http.get('json/' + version + '/' +module + '/index.json')
-                  .then(filterDocJson($sce, version))
-                  .then(setMethod($location, method, version));
-            }
-          }
-        }
-      })
-      .when('/docs/:version/:module/:class/:method', {
-        controller: 'DocsCtrl',
-        templateUrl: 'components/docs/docs.html',
-        resolve: {
-          methods: function($q, $http, $route, $sce, $location) {
-            var version = $route.current.params.version;
-            var module = $route.current.params.module;
-            var cl = $route.current.params.class;
-            var method = $route.current.params.method;
-            return $http.get('json/' + version + '/' + module + '/' + cl + '.json')
-                .then(filterDocJson($sce, version))
-                .then(setMethod($location, method, version));
-          }
-        }
+        resolve: { methods: getMethods, links: getLinks }
       });
   })
 
   .run(function($location, $route, $rootScope, versions) {
+    'use strict';
+
     $rootScope.$on('$routeChangeStart', function(event, route) {
       var url = $location.path();
       if (url.indexOf('/docs/') === -1 || (!route.params || !route.params.version)) {
@@ -217,7 +220,19 @@ angular
     });
   })
 
-  .controller('DocsCtrl', function($location, $scope, $routeParams, methods, $http, versions) {
+  .directive('docsExample', function($compile) {
+    'use strict';
+
+    return {
+      link: function(scope, element, attr) {
+        scope.$watch(attr.ngBindHtml, function() {
+          $compile(element.contents())(scope);
+        }, true);
+      }
+    };
+  })
+
+  .controller('DocsCtrl', function($location, $scope, $routeParams, methods, $http, links, versions) {
     'use strict';
 
     $scope.isActiveUrl = function(url) {
@@ -236,44 +251,17 @@ angular
     $scope.showReference = true;
     $scope.activeUrl = '#' + $location.path();
     $scope.singleMethod = methods.singleMethod;
-    $scope.noPermalink = methods.singleMethod || methods.noPermalink;
-    $scope.methods = methods;
     $scope.module = $routeParams.module;
+    $scope.methods = methods;
     $scope.version = $routeParams.version;
     $scope.isLatestVersion = $scope.version == versions[0];
     $scope.versions = versions;
-    var baseUrl = '#/docs/' + $scope.version;
-    /*
-    TODO(silvano): future versions will introduce new pages, so the list below will have
-    to be generated according to the specific version
-    */
-    $scope.pages = [
-      {
-        title: 'gcloud',
-        url: baseUrl
-      },
-      {
-        title: 'Datastore',
-        url: baseUrl + '/datastore',
-        pages: [
-          {
-            title: 'Dataset',
-            url: '/dataset'
-          },
-          {
-            title: 'Query',
-            url: '/query'
-          }
-        ]
-      },
-      {
-        title: 'Storage',
-        url: baseUrl + '/storage'
-      }
-    ];
+    $scope.links = links;
   })
 
   .controller('HistoryCtrl', function($scope, versions) {
+    'use strict';
+
     $scope.pageTitle = 'Node.js Docs Versions';
     $scope.showHistory = true;
     $scope.versions = versions;
diff --git a/docs/index.html b/docs/index.html
index daeec618fc77..8f73f6435c50 100755
--- a/docs/index.html
+++ b/docs/index.html
@@ -26,8 +26,11 @@
     <script src="//code.angularjs.org/1.2.23/angular-route.js"></script>
     <script src="//yandex.st/highlightjs/8.0/highlight.min.js"></script>
     <script src="//pc035860.github.io/angular-highlightjs/angular-highlightjs.min.js"></script>
+    <script src="lib/semver.js"></script>
     <script src="home.js"></script>
     <script src="components/docs/docs.js"></script>
+    <script src="components/docs/docs-services.js"></script>
+    <script src="components/docs/docs-values.js"></script>
 
     <script>
       (function() {
diff --git a/docs/lib/semver.js b/docs/lib/semver.js
new file mode 100644
index 000000000000..afb68ac0c45a
--- /dev/null
+++ b/docs/lib/semver.js
@@ -0,0 +1,1098 @@
+;(function(exports) {
+
+// export the class if we are in a Node-like system.
+if (typeof module === 'object' && module.exports === exports)
+  exports = module.exports = SemVer;
+
+// The debug function is excluded entirely from the minified version.
+
+// Note: this is the semver.org version of the spec that it implements
+// Not necessarily the package version of this code.
+exports.SEMVER_SPEC_VERSION = '2.0.0';
+
+// The actual regexps go on exports.re
+var re = exports.re = [];
+var src = exports.src = [];
+var R = 0;
+
+// The following Regular Expressions can be used for tokenizing,
+// validating, and parsing SemVer version strings.
+
+// ## Numeric Identifier
+// A single `0`, or a non-zero digit followed by zero or more digits.
+
+var NUMERICIDENTIFIER = R++;
+src[NUMERICIDENTIFIER] = '0|[1-9]\\d*';
+var NUMERICIDENTIFIERLOOSE = R++;
+src[NUMERICIDENTIFIERLOOSE] = '[0-9]+';
+
+
+// ## Non-numeric Identifier
+// Zero or more digits, followed by a letter or hyphen, and then zero or
+// more letters, digits, or hyphens.
+
+var NONNUMERICIDENTIFIER = R++;
+src[NONNUMERICIDENTIFIER] = '\\d*[a-zA-Z-][a-zA-Z0-9-]*';
+
+
+// ## Main Version
+// Three dot-separated numeric identifiers.
+
+var MAINVERSION = R++;
+src[MAINVERSION] = '(' + src[NUMERICIDENTIFIER] + ')\\.' +
+                   '(' + src[NUMERICIDENTIFIER] + ')\\.' +
+                   '(' + src[NUMERICIDENTIFIER] + ')';
+
+var MAINVERSIONLOOSE = R++;
+src[MAINVERSIONLOOSE] = '(' + src[NUMERICIDENTIFIERLOOSE] + ')\\.' +
+                        '(' + src[NUMERICIDENTIFIERLOOSE] + ')\\.' +
+                        '(' + src[NUMERICIDENTIFIERLOOSE] + ')';
+
+// ## Pre-release Version Identifier
+// A numeric identifier, or a non-numeric identifier.
+
+var PRERELEASEIDENTIFIER = R++;
+src[PRERELEASEIDENTIFIER] = '(?:' + src[NUMERICIDENTIFIER] +
+                            '|' + src[NONNUMERICIDENTIFIER] + ')';
+
+var PRERELEASEIDENTIFIERLOOSE = R++;
+src[PRERELEASEIDENTIFIERLOOSE] = '(?:' + src[NUMERICIDENTIFIERLOOSE] +
+                                 '|' + src[NONNUMERICIDENTIFIER] + ')';
+
+
+// ## Pre-release Version
+// Hyphen, followed by one or more dot-separated pre-release version
+// identifiers.
+
+var PRERELEASE = R++;
+src[PRERELEASE] = '(?:-(' + src[PRERELEASEIDENTIFIER] +
+                  '(?:\\.' + src[PRERELEASEIDENTIFIER] + ')*))';
+
+var PRERELEASELOOSE = R++;
+src[PRERELEASELOOSE] = '(?:-?(' + src[PRERELEASEIDENTIFIERLOOSE] +
+                       '(?:\\.' + src[PRERELEASEIDENTIFIERLOOSE] + ')*))';
+
+// ## Build Metadata Identifier
+// Any combination of digits, letters, or hyphens.
+
+var BUILDIDENTIFIER = R++;
+src[BUILDIDENTIFIER] = '[0-9A-Za-z-]+';
+
+// ## Build Metadata
+// Plus sign, followed by one or more period-separated build metadata
+// identifiers.
+
+var BUILD = R++;
+src[BUILD] = '(?:\\+(' + src[BUILDIDENTIFIER] +
+             '(?:\\.' + src[BUILDIDENTIFIER] + ')*))';
+
+
+// ## Full Version String
+// A main version, followed optionally by a pre-release version and
+// build metadata.
+
+// Note that the only major, minor, patch, and pre-release sections of
+// the version string are capturing groups.  The build metadata is not a
+// capturing group, because it should not ever be used in version
+// comparison.
+
+var FULL = R++;
+var FULLPLAIN = 'v?' + src[MAINVERSION] +
+                src[PRERELEASE] + '?' +
+                src[BUILD] + '?';
+
+src[FULL] = '^' + FULLPLAIN + '$';
+
+// like full, but allows v1.2.3 and =1.2.3, which people do sometimes.
+// also, 1.0.0alpha1 (prerelease without the hyphen) which is pretty
+// common in the npm registry.
+var LOOSEPLAIN = '[v=\\s]*' + src[MAINVERSIONLOOSE] +
+                 src[PRERELEASELOOSE] + '?' +
+                 src[BUILD] + '?';
+
+var LOOSE = R++;
+src[LOOSE] = '^' + LOOSEPLAIN + '$';
+
+var GTLT = R++;
+src[GTLT] = '((?:<|>)?=?)';
+
+// Something like "2.*" or "1.2.x".
+// Note that "x.x" is a valid xRange identifer, meaning "any version"
+// Only the first item is strictly required.
+var XRANGEIDENTIFIERLOOSE = R++;
+src[XRANGEIDENTIFIERLOOSE] = src[NUMERICIDENTIFIERLOOSE] + '|x|X|\\*';
+var XRANGEIDENTIFIER = R++;
+src[XRANGEIDENTIFIER] = src[NUMERICIDENTIFIER] + '|x|X|\\*';
+
+var XRANGEPLAIN = R++;
+src[XRANGEPLAIN] = '[v=\\s]*(' + src[XRANGEIDENTIFIER] + ')' +
+                   '(?:\\.(' + src[XRANGEIDENTIFIER] + ')' +
+                   '(?:\\.(' + src[XRANGEIDENTIFIER] + ')' +
+                   '(?:' + src[PRERELEASE] + ')?' +
+                   src[BUILD] + '?' +
+                   ')?)?';
+
+var XRANGEPLAINLOOSE = R++;
+src[XRANGEPLAINLOOSE] = '[v=\\s]*(' + src[XRANGEIDENTIFIERLOOSE] + ')' +
+                        '(?:\\.(' + src[XRANGEIDENTIFIERLOOSE] + ')' +
+                        '(?:\\.(' + src[XRANGEIDENTIFIERLOOSE] + ')' +
+                        '(?:' + src[PRERELEASELOOSE] + ')?' +
+                        src[BUILD] + '?' +
+                        ')?)?';
+
+var XRANGE = R++;
+src[XRANGE] = '^' + src[GTLT] + '\\s*' + src[XRANGEPLAIN] + '$';
+var XRANGELOOSE = R++;
+src[XRANGELOOSE] = '^' + src[GTLT] + '\\s*' + src[XRANGEPLAINLOOSE] + '$';
+
+// Tilde ranges.
+// Meaning is "reasonably at or greater than"
+var LONETILDE = R++;
+src[LONETILDE] = '(?:~>?)';
+
+var TILDETRIM = R++;
+src[TILDETRIM] = '(\\s*)' + src[LONETILDE] + '\\s+';
+re[TILDETRIM] = new RegExp(src[TILDETRIM], 'g');
+var tildeTrimReplace = '$1~';
+
+var TILDE = R++;
+src[TILDE] = '^' + src[LONETILDE] + src[XRANGEPLAIN] + '$';
+var TILDELOOSE = R++;
+src[TILDELOOSE] = '^' + src[LONETILDE] + src[XRANGEPLAINLOOSE] + '$';
+
+// Caret ranges.
+// Meaning is "at least and backwards compatible with"
+var LONECARET = R++;
+src[LONECARET] = '(?:\\^)';
+
+var CARETTRIM = R++;
+src[CARETTRIM] = '(\\s*)' + src[LONECARET] + '\\s+';
+re[CARETTRIM] = new RegExp(src[CARETTRIM], 'g');
+var caretTrimReplace = '$1^';
+
+var CARET = R++;
+src[CARET] = '^' + src[LONECARET] + src[XRANGEPLAIN] + '$';
+var CARETLOOSE = R++;
+src[CARETLOOSE] = '^' + src[LONECARET] + src[XRANGEPLAINLOOSE] + '$';
+
+// A simple gt/lt/eq thing, or just "" to indicate "any version"
+var COMPARATORLOOSE = R++;
+src[COMPARATORLOOSE] = '^' + src[GTLT] + '\\s*(' + LOOSEPLAIN + ')$|^$';
+var COMPARATOR = R++;
+src[COMPARATOR] = '^' + src[GTLT] + '\\s*(' + FULLPLAIN + ')$|^$';
+
+
+// An expression to strip any whitespace between the gtlt and the thing
+// it modifies, so that `> 1.2.3` ==> `>1.2.3`
+var COMPARATORTRIM = R++;
+src[COMPARATORTRIM] = '(\\s*)' + src[GTLT] +
+                      '\\s*(' + LOOSEPLAIN + '|' + src[XRANGEPLAIN] + ')';
+
+// this one has to use the /g flag
+re[COMPARATORTRIM] = new RegExp(src[COMPARATORTRIM], 'g');
+var comparatorTrimReplace = '$1$2$3';
+
+
+// Something like `1.2.3 - 1.2.4`
+// Note that these all use the loose form, because they'll be
+// checked against either the strict or loose comparator form
+// later.
+var HYPHENRANGE = R++;
+src[HYPHENRANGE] = '^\\s*(' + src[XRANGEPLAIN] + ')' +
+                   '\\s+-\\s+' +
+                   '(' + src[XRANGEPLAIN] + ')' +
+                   '\\s*$';
+
+var HYPHENRANGELOOSE = R++;
+src[HYPHENRANGELOOSE] = '^\\s*(' + src[XRANGEPLAINLOOSE] + ')' +
+                        '\\s+-\\s+' +
+                        '(' + src[XRANGEPLAINLOOSE] + ')' +
+                        '\\s*$';
+
+// Star ranges basically just allow anything at all.
+var STAR = R++;
+src[STAR] = '(<|>)?=?\\s*\\*';
+
+// Compile to actual regexp objects.
+// All are flag-free, unless they were created above with a flag.
+for (var i = 0; i < R; i++) {
+  ;
+  if (!re[i])
+    re[i] = new RegExp(src[i]);
+}
+
+exports.parse = parse;
+function parse(version, loose) {
+  var r = loose ? re[LOOSE] : re[FULL];
+  return (r.test(version)) ? new SemVer(version, loose) : null;
+}
+
+exports.valid = valid;
+function valid(version, loose) {
+  var v = parse(version, loose);
+  return v ? v.version : null;
+}
+
+
+exports.clean = clean;
+function clean(version, loose) {
+  var s = parse(version.trim().replace(/^[=v]+/, ''), loose);
+  return s ? s.version : null;
+}
+
+exports.SemVer = SemVer;
+
+function SemVer(version, loose) {
+  if (version instanceof SemVer) {
+    if (version.loose === loose)
+      return version;
+    else
+      version = version.version;
+  } else if (typeof version !== 'string') {
+    throw new TypeError('Invalid Version: ' + version);
+  }
+
+  if (!(this instanceof SemVer))
+    return new SemVer(version, loose);
+
+  ;
+  this.loose = loose;
+  var m = version.trim().match(loose ? re[LOOSE] : re[FULL]);
+
+  if (!m)
+    throw new TypeError('Invalid Version: ' + version);
+
+  this.raw = version;
+
+  // these are actually numbers
+  this.major = +m[1];
+  this.minor = +m[2];
+  this.patch = +m[3];
+
+  // numberify any prerelease numeric ids
+  if (!m[4])
+    this.prerelease = [];
+  else
+    this.prerelease = m[4].split('.').map(function(id) {
+      return (/^[0-9]+$/.test(id)) ? +id : id;
+    });
+
+  this.build = m[5] ? m[5].split('.') : [];
+  this.format();
+}
+
+SemVer.prototype.format = function() {
+  this.version = this.major + '.' + this.minor + '.' + this.patch;
+  if (this.prerelease.length)
+    this.version += '-' + this.prerelease.join('.');
+  return this.version;
+};
+
+SemVer.prototype.inspect = function() {
+  return '<SemVer "' + this + '">';
+};
+
+SemVer.prototype.toString = function() {
+  return this.version;
+};
+
+SemVer.prototype.compare = function(other) {
+  ;
+  if (!(other instanceof SemVer))
+    other = new SemVer(other, this.loose);
+
+  return this.compareMain(other) || this.comparePre(other);
+};
+
+SemVer.prototype.compareMain = function(other) {
+  if (!(other instanceof SemVer))
+    other = new SemVer(other, this.loose);
+
+  return compareIdentifiers(this.major, other.major) ||
+         compareIdentifiers(this.minor, other.minor) ||
+         compareIdentifiers(this.patch, other.patch);
+};
+
+SemVer.prototype.comparePre = function(other) {
+  if (!(other instanceof SemVer))
+    other = new SemVer(other, this.loose);
+
+  // NOT having a prerelease is > having one
+  if (this.prerelease.length && !other.prerelease.length)
+    return -1;
+  else if (!this.prerelease.length && other.prerelease.length)
+    return 1;
+  else if (!this.prerelease.length && !other.prerelease.length)
+    return 0;
+
+  var i = 0;
+  do {
+    var a = this.prerelease[i];
+    var b = other.prerelease[i];
+    ;
+    if (a === undefined && b === undefined)
+      return 0;
+    else if (b === undefined)
+      return 1;
+    else if (a === undefined)
+      return -1;
+    else if (a === b)
+      continue;
+    else
+      return compareIdentifiers(a, b);
+  } while (++i);
+};
+
+// preminor will bump the version up to the next minor release, and immediately
+// down to pre-release. premajor and prepatch work the same way.
+SemVer.prototype.inc = function(release) {
+  switch (release) {
+    case 'premajor':
+      this.prerelease.length = 0;
+      this.patch = 0;
+      this.minor = 0;
+      this.major++;
+      this.inc('pre');
+      break;
+    case 'preminor':
+      this.prerelease.length = 0;
+      this.patch = 0;
+      this.minor++;
+      this.inc('pre');
+      break;
+    case 'prepatch':
+      // If this is already a prerelease, it will bump to the next version
+      // drop any prereleases that might already exist, since they are not
+      // relevant at this point.
+      this.prerelease.length = 0;
+      this.inc('patch');
+      this.inc('pre');
+      break;
+    // If the input is a non-prerelease version, this acts the same as
+    // prepatch.
+    case 'prerelease':
+      if (this.prerelease.length === 0)
+        this.inc('patch');
+      this.inc('pre');
+      break;
+
+    case 'major':
+      // If this is a pre-major version, bump up to the same major version.
+      // Otherwise increment major.
+      // 1.0.0-5 bumps to 1.0.0
+      // 1.1.0 bumps to 2.0.0
+      if (this.minor !== 0 || this.patch !== 0 || this.prerelease.length === 0)
+        this.major++;
+      this.minor = 0;
+      this.patch = 0;
+      this.prerelease = [];
+      break;
+    case 'minor':
+      // If this is a pre-minor version, bump up to the same minor version.
+      // Otherwise increment minor.
+      // 1.2.0-5 bumps to 1.2.0
+      // 1.2.1 bumps to 1.3.0
+      if (this.patch !== 0 || this.prerelease.length === 0)
+        this.minor++;
+      this.patch = 0;
+      this.prerelease = [];
+      break;
+    case 'patch':
+      // If this is not a pre-release version, it will increment the patch.
+      // If it is a pre-release it will bump up to the same patch version.
+      // 1.2.0-5 patches to 1.2.0
+      // 1.2.0 patches to 1.2.1
+      if (this.prerelease.length === 0)
+        this.patch++;
+      this.prerelease = [];
+      break;
+    // This probably shouldn't be used publicly.
+    // 1.0.0 "pre" would become 1.0.0 which is the wrong direction.
+    case 'pre':
+      if (this.prerelease.length === 0)
+        this.prerelease = [0];
+      else {
+        var i = this.prerelease.length;
+        while (--i >= 0) {
+          if (typeof this.prerelease[i] === 'number') {
+            this.prerelease[i]++;
+            i = -2;
+          }
+        }
+        if (i === -1) // didn't increment anything
+          this.prerelease.push(0);
+      }
+      break;
+
+    default:
+      throw new Error('invalid increment argument: ' + release);
+  }
+  this.format();
+  return this;
+};
+
+exports.inc = inc;
+function inc(version, release, loose) {
+  try {
+    return new SemVer(version, loose).inc(release).version;
+  } catch (er) {
+    return null;
+  }
+}
+
+exports.compareIdentifiers = compareIdentifiers;
+
+var numeric = /^[0-9]+$/;
+function compareIdentifiers(a, b) {
+  var anum = numeric.test(a);
+  var bnum = numeric.test(b);
+
+  if (anum && bnum) {
+    a = +a;
+    b = +b;
+  }
+
+  return (anum && !bnum) ? -1 :
+         (bnum && !anum) ? 1 :
+         a < b ? -1 :
+         a > b ? 1 :
+         0;
+}
+
+exports.rcompareIdentifiers = rcompareIdentifiers;
+function rcompareIdentifiers(a, b) {
+  return compareIdentifiers(b, a);
+}
+
+exports.compare = compare;
+function compare(a, b, loose) {
+  return new SemVer(a, loose).compare(b);
+}
+
+exports.compareLoose = compareLoose;
+function compareLoose(a, b) {
+  return compare(a, b, true);
+}
+
+exports.rcompare = rcompare;
+function rcompare(a, b, loose) {
+  return compare(b, a, loose);
+}
+
+exports.sort = sort;
+function sort(list, loose) {
+  return list.sort(function(a, b) {
+    return exports.compare(a, b, loose);
+  });
+}
+
+exports.rsort = rsort;
+function rsort(list, loose) {
+  return list.sort(function(a, b) {
+    return exports.rcompare(a, b, loose);
+  });
+}
+
+exports.gt = gt;
+function gt(a, b, loose) {
+  return compare(a, b, loose) > 0;
+}
+
+exports.lt = lt;
+function lt(a, b, loose) {
+  return compare(a, b, loose) < 0;
+}
+
+exports.eq = eq;
+function eq(a, b, loose) {
+  return compare(a, b, loose) === 0;
+}
+
+exports.neq = neq;
+function neq(a, b, loose) {
+  return compare(a, b, loose) !== 0;
+}
+
+exports.gte = gte;
+function gte(a, b, loose) {
+  return compare(a, b, loose) >= 0;
+}
+
+exports.lte = lte;
+function lte(a, b, loose) {
+  return compare(a, b, loose) <= 0;
+}
+
+exports.cmp = cmp;
+function cmp(a, op, b, loose) {
+  var ret;
+  switch (op) {
+    case '===':
+      if (typeof a === 'object') a = a.version;
+      if (typeof b === 'object') b = b.version;
+      ret = a === b;
+      break;
+    case '!==':
+      if (typeof a === 'object') a = a.version;
+      if (typeof b === 'object') b = b.version;
+      ret = a !== b;
+      break;
+    case '': case '=': case '==': ret = eq(a, b, loose); break;
+    case '!=': ret = neq(a, b, loose); break;
+    case '>': ret = gt(a, b, loose); break;
+    case '>=': ret = gte(a, b, loose); break;
+    case '<': ret = lt(a, b, loose); break;
+    case '<=': ret = lte(a, b, loose); break;
+    default: throw new TypeError('Invalid operator: ' + op);
+  }
+  return ret;
+}
+
+exports.Comparator = Comparator;
+function Comparator(comp, loose) {
+  if (comp instanceof Comparator) {
+    if (comp.loose === loose)
+      return comp;
+    else
+      comp = comp.value;
+  }
+
+  if (!(this instanceof Comparator))
+    return new Comparator(comp, loose);
+
+  ;
+  this.loose = loose;
+  this.parse(comp);
+
+  if (this.semver === ANY)
+    this.value = '';
+  else
+    this.value = this.operator + this.semver.version;
+
+  ;
+}
+
+var ANY = {};
+Comparator.prototype.parse = function(comp) {
+  var r = this.loose ? re[COMPARATORLOOSE] : re[COMPARATOR];
+  var m = comp.match(r);
+
+  if (!m)
+    throw new TypeError('Invalid comparator: ' + comp);
+
+  this.operator = m[1];
+  if (this.operator === '=')
+    this.operator = '';
+
+  // if it literally is just '>' or '' then allow anything.
+  if (!m[2])
+    this.semver = ANY;
+  else
+    this.semver = new SemVer(m[2], this.loose);
+};
+
+Comparator.prototype.inspect = function() {
+  return '<SemVer Comparator "' + this + '">';
+};
+
+Comparator.prototype.toString = function() {
+  return this.value;
+};
+
+Comparator.prototype.test = function(version) {
+  ;
+
+  if (this.semver === ANY)
+    return true;
+
+  if (typeof version === 'string')
+    version = new SemVer(version, this.loose);
+
+  return cmp(version, this.operator, this.semver, this.loose);
+};
+
+
+exports.Range = Range;
+function Range(range, loose) {
+  if ((range instanceof Range) && range.loose === loose)
+    return range;
+
+  if (!(this instanceof Range))
+    return new Range(range, loose);
+
+  this.loose = loose;
+
+  // First, split based on boolean or ||
+  this.raw = range;
+  this.set = range.split(/\s*\|\|\s*/).map(function(range) {
+    return this.parseRange(range.trim());
+  }, this).filter(function(c) {
+    // throw out any that are not relevant for whatever reason
+    return c.length;
+  });
+
+  if (!this.set.length) {
+    throw new TypeError('Invalid SemVer Range: ' + range);
+  }
+
+  this.format();
+}
+
+Range.prototype.inspect = function() {
+  return '<SemVer Range "' + this.range + '">';
+};
+
+Range.prototype.format = function() {
+  this.range = this.set.map(function(comps) {
+    return comps.join(' ').trim();
+  }).join('||').trim();
+  return this.range;
+};
+
+Range.prototype.toString = function() {
+  return this.range;
+};
+
+Range.prototype.parseRange = function(range) {
+  var loose = this.loose;
+  range = range.trim();
+  ;
+  // `1.2.3 - 1.2.4` => `>=1.2.3 <=1.2.4`
+  var hr = loose ? re[HYPHENRANGELOOSE] : re[HYPHENRANGE];
+  range = range.replace(hr, hyphenReplace);
+  ;
+  // `> 1.2.3 < 1.2.5` => `>1.2.3 <1.2.5`
+  range = range.replace(re[COMPARATORTRIM], comparatorTrimReplace);
+  ;
+
+  // `~ 1.2.3` => `~1.2.3`
+  range = range.replace(re[TILDETRIM], tildeTrimReplace);
+
+  // `^ 1.2.3` => `^1.2.3`
+  range = range.replace(re[CARETTRIM], caretTrimReplace);
+
+  // normalize spaces
+  range = range.split(/\s+/).join(' ');
+
+  // At this point, the range is completely trimmed and
+  // ready to be split into comparators.
+
+  var compRe = loose ? re[COMPARATORLOOSE] : re[COMPARATOR];
+  var set = range.split(' ').map(function(comp) {
+    return parseComparator(comp, loose);
+  }).join(' ').split(/\s+/);
+  if (this.loose) {
+    // in loose mode, throw out any that are not valid comparators
+    set = set.filter(function(comp) {
+      return !!comp.match(compRe);
+    });
+  }
+  set = set.map(function(comp) {
+    return new Comparator(comp, loose);
+  });
+
+  return set;
+};
+
+// Mostly just for testing and legacy API reasons
+exports.toComparators = toComparators;
+function toComparators(range, loose) {
+  return new Range(range, loose).set.map(function(comp) {
+    return comp.map(function(c) {
+      return c.value;
+    }).join(' ').trim().split(' ');
+  });
+}
+
+// comprised of xranges, tildes, stars, and gtlt's at this point.
+// already replaced the hyphen ranges
+// turn into a set of JUST comparators.
+function parseComparator(comp, loose) {
+  ;
+  comp = replaceCarets(comp, loose);
+  ;
+  comp = replaceTildes(comp, loose);
+  ;
+  comp = replaceXRanges(comp, loose);
+  ;
+  comp = replaceStars(comp, loose);
+  ;
+  return comp;
+}
+
+function isX(id) {
+  return !id || id.toLowerCase() === 'x' || id === '*';
+}
+
+// ~, ~> --> * (any, kinda silly)
+// ~2, ~2.x, ~2.x.x, ~>2, ~>2.x ~>2.x.x --> >=2.0.0 <3.0.0
+// ~2.0, ~2.0.x, ~>2.0, ~>2.0.x --> >=2.0.0 <2.1.0
+// ~1.2, ~1.2.x, ~>1.2, ~>1.2.x --> >=1.2.0 <1.3.0
+// ~1.2.3, ~>1.2.3 --> >=1.2.3 <1.3.0
+// ~1.2.0, ~>1.2.0 --> >=1.2.0 <1.3.0
+function replaceTildes(comp, loose) {
+  return comp.trim().split(/\s+/).map(function(comp) {
+    return replaceTilde(comp, loose);
+  }).join(' ');
+}
+
+function replaceTilde(comp, loose) {
+  var r = loose ? re[TILDELOOSE] : re[TILDE];
+  return comp.replace(r, function(_, M, m, p, pr) {
+    ;
+    var ret;
+
+    if (isX(M))
+      ret = '';
+    else if (isX(m))
+      ret = '>=' + M + '.0.0 <' + (+M + 1) + '.0.0';
+    else if (isX(p))
+      // ~1.2 == >=1.2.0- <1.3.0-
+      ret = '>=' + M + '.' + m + '.0 <' + M + '.' + (+m + 1) + '.0';
+    else if (pr) {
+      ;
+      if (pr.charAt(0) !== '-')
+        pr = '-' + pr;
+      ret = '>=' + M + '.' + m + '.' + p + pr +
+            ' <' + M + '.' + (+m + 1) + '.0';
+    } else
+      // ~1.2.3 == >=1.2.3 <1.3.0
+      ret = '>=' + M + '.' + m + '.' + p +
+            ' <' + M + '.' + (+m + 1) + '.0';
+
+    ;
+    return ret;
+  });
+}
+
+// ^ --> * (any, kinda silly)
+// ^2, ^2.x, ^2.x.x --> >=2.0.0 <3.0.0
+// ^2.0, ^2.0.x --> >=2.0.0 <3.0.0
+// ^1.2, ^1.2.x --> >=1.2.0 <2.0.0
+// ^1.2.3 --> >=1.2.3 <2.0.0
+// ^1.2.0 --> >=1.2.0 <2.0.0
+function replaceCarets(comp, loose) {
+  return comp.trim().split(/\s+/).map(function(comp) {
+    return replaceCaret(comp, loose);
+  }).join(' ');
+}
+
+function replaceCaret(comp, loose) {
+  ;
+  var r = loose ? re[CARETLOOSE] : re[CARET];
+  return comp.replace(r, function(_, M, m, p, pr) {
+    ;
+    var ret;
+
+    if (isX(M))
+      ret = '';
+    else if (isX(m))
+      ret = '>=' + M + '.0.0 <' + (+M + 1) + '.0.0';
+    else if (isX(p)) {
+      if (M === '0')
+        ret = '>=' + M + '.' + m + '.0 <' + M + '.' + (+m + 1) + '.0';
+      else
+        ret = '>=' + M + '.' + m + '.0 <' + (+M + 1) + '.0.0';
+    } else if (pr) {
+      ;
+      if (pr.charAt(0) !== '-')
+        pr = '-' + pr;
+      if (M === '0') {
+        if (m === '0')
+          ret = '>=' + M + '.' + m + '.' + p + pr +
+                ' <' + M + '.' + m + '.' + (+p + 1);
+        else
+          ret = '>=' + M + '.' + m + '.' + p + pr +
+                ' <' + M + '.' + (+m + 1) + '.0';
+      } else
+        ret = '>=' + M + '.' + m + '.' + p + pr +
+              ' <' + (+M + 1) + '.0.0';
+    } else {
+      ;
+      if (M === '0') {
+        if (m === '0')
+          ret = '>=' + M + '.' + m + '.' + p +
+                ' <' + M + '.' + m + '.' + (+p + 1);
+        else
+          ret = '>=' + M + '.' + m + '.' + p +
+                ' <' + M + '.' + (+m + 1) + '.0';
+      } else
+        ret = '>=' + M + '.' + m + '.' + p +
+              ' <' + (+M + 1) + '.0.0';
+    }
+
+    ;
+    return ret;
+  });
+}
+
+function replaceXRanges(comp, loose) {
+  ;
+  return comp.split(/\s+/).map(function(comp) {
+    return replaceXRange(comp, loose);
+  }).join(' ');
+}
+
+function replaceXRange(comp, loose) {
+  comp = comp.trim();
+  var r = loose ? re[XRANGELOOSE] : re[XRANGE];
+  return comp.replace(r, function(ret, gtlt, M, m, p, pr) {
+    ;
+    var xM = isX(M);
+    var xm = xM || isX(m);
+    var xp = xm || isX(p);
+    var anyX = xp;
+
+    if (gtlt === '=' && anyX)
+      gtlt = '';
+
+    if (gtlt && anyX) {
+      // replace X with 0
+      if (xM)
+        M = 0;
+      if (xm)
+        m = 0;
+      if (xp)
+        p = 0;
+
+      if (gtlt === '>') {
+        // >1 => >=2.0.0
+        // >1.2 => >=1.3.0
+        // >1.2.3 => >= 1.2.4
+        gtlt = '>=';
+        if (xM) {
+          // no change
+        } else if (xm) {
+          M = +M + 1;
+          m = 0;
+          p = 0;
+        } else if (xp) {
+          m = +m + 1;
+          p = 0;
+        }
+      }
+
+
+      ret = gtlt + M + '.' + m + '.' + p;
+    } else if (xM) {
+      // allow any
+      ret = '*';
+    } else if (xm) {
+      ret = '>=' + M + '.0.0 <' + (+M + 1) + '.0.0';
+    } else if (xp) {
+      ret = '>=' + M + '.' + m + '.0 <' + M + '.' + (+m + 1) + '.0';
+    }
+
+    ;
+
+    return ret;
+  });
+}
+
+// Because * is AND-ed with everything else in the comparator,
+// and '' means "any version", just remove the *s entirely.
+function replaceStars(comp, loose) {
+  ;
+  // Looseness is ignored here.  star is always as loose as it gets!
+  return comp.trim().replace(re[STAR], '');
+}
+
+// This function is passed to string.replace(re[HYPHENRANGE])
+// M, m, patch, prerelease, build
+// 1.2 - 3.4.5 => >=1.2.0 <=3.4.5
+// 1.2.3 - 3.4 => >=1.2.0 <3.5.0 Any 3.4.x will do
+// 1.2 - 3.4 => >=1.2.0 <3.5.0
+function hyphenReplace($0,
+                       from, fM, fm, fp, fpr, fb,
+                       to, tM, tm, tp, tpr, tb) {
+
+  if (isX(fM))
+    from = '';
+  else if (isX(fm))
+    from = '>=' + fM + '.0.0';
+  else if (isX(fp))
+    from = '>=' + fM + '.' + fm + '.0';
+  else
+    from = '>=' + from;
+
+  if (isX(tM))
+    to = '';
+  else if (isX(tm))
+    to = '<' + (+tM + 1) + '.0.0';
+  else if (isX(tp))
+    to = '<' + tM + '.' + (+tm + 1) + '.0';
+  else if (tpr)
+    to = '<=' + tM + '.' + tm + '.' + tp + '-' + tpr;
+  else
+    to = '<=' + to;
+
+  return (from + ' ' + to).trim();
+}
+
+
+// if ANY of the sets match ALL of its comparators, then pass
+Range.prototype.test = function(version) {
+  if (!version)
+    return false;
+
+  if (typeof version === 'string')
+    version = new SemVer(version, this.loose);
+
+  for (var i = 0; i < this.set.length; i++) {
+    if (testSet(this.set[i], version))
+      return true;
+  }
+  return false;
+};
+
+function testSet(set, version) {
+  for (var i = 0; i < set.length; i++) {
+    if (!set[i].test(version))
+      return false;
+  }
+
+  if (version.prerelease.length) {
+    // Find the set of versions that are allowed to have prereleases
+    // For example, ^1.2.3-pr.1 desugars to >=1.2.3-pr.1 <2.0.0
+    // That should allow `1.2.3-pr.2` to pass.
+    // However, `1.2.4-alpha.notready` should NOT be allowed,
+    // even though it's within the range set by the comparators.
+    for (var i = 0; i < set.length; i++) {
+      ;
+      if (set[i].semver === ANY)
+        return true;
+
+      if (set[i].semver.prerelease.length > 0) {
+        var allowed = set[i].semver;
+        if (allowed.major === version.major &&
+            allowed.minor === version.minor &&
+            allowed.patch === version.patch)
+          return true;
+      }
+    }
+
+    // Version has a -pre, but it's not one of the ones we like.
+    return false;
+  }
+
+  return true;
+}
+
+exports.satisfies = satisfies;
+function satisfies(version, range, loose) {
+  try {
+    range = new Range(range, loose);
+  } catch (er) {
+    return false;
+  }
+  return range.test(version);
+}
+
+exports.maxSatisfying = maxSatisfying;
+function maxSatisfying(versions, range, loose) {
+  return versions.filter(function(version) {
+    return satisfies(version, range, loose);
+  }).sort(function(a, b) {
+    return rcompare(a, b, loose);
+  })[0] || null;
+}
+
+exports.validRange = validRange;
+function validRange(range, loose) {
+  try {
+    // Return '*' instead of '' so that truthiness works.
+    // This will throw if it's invalid anyway
+    return new Range(range, loose).range || '*';
+  } catch (er) {
+    return null;
+  }
+}
+
+// Determine if version is less than all the versions possible in the range
+exports.ltr = ltr;
+function ltr(version, range, loose) {
+  return outside(version, range, '<', loose);
+}
+
+// Determine if version is greater than all the versions possible in the range.
+exports.gtr = gtr;
+function gtr(version, range, loose) {
+  return outside(version, range, '>', loose);
+}
+
+exports.outside = outside;
+function outside(version, range, hilo, loose) {
+  version = new SemVer(version, loose);
+  range = new Range(range, loose);
+
+  var gtfn, ltefn, ltfn, comp, ecomp;
+  switch (hilo) {
+    case '>':
+      gtfn = gt;
+      ltefn = lte;
+      ltfn = lt;
+      comp = '>';
+      ecomp = '>=';
+      break;
+    case '<':
+      gtfn = lt;
+      ltefn = gte;
+      ltfn = gt;
+      comp = '<';
+      ecomp = '<=';
+      break;
+    default:
+      throw new TypeError('Must provide a hilo val of "<" or ">"');
+  }
+
+  // If it satisifes the range it is not outside
+  if (satisfies(version, range, loose)) {
+    return false;
+  }
+
+  // From now on, variable terms are as if we're in "gtr" mode.
+  // but note that everything is flipped for the "ltr" function.
+
+  for (var i = 0; i < range.set.length; ++i) {
+    var comparators = range.set[i];
+
+    var high = null;
+    var low = null;
+
+    comparators.forEach(function(comparator) {
+      high = high || comparator;
+      low = low || comparator;
+      if (gtfn(comparator.semver, high.semver, loose)) {
+        high = comparator;
+      } else if (ltfn(comparator.semver, low.semver, loose)) {
+        low = comparator;
+      }
+    });
+
+    // If the edge version comparator has a operator then our version
+    // isn't outside it
+    if (high.operator === comp || high.operator === ecomp) {
+      return false;
+    }
+
+    // If the lowest version comparator has an operator and our version
+    // is less than it then it isn't higher than the range
+    if ((!low.operator || low.operator === comp) &&
+        ltefn(version, low.semver)) {
+      return false;
+    } else if (low.operator === ecomp && ltfn(version, low.semver)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+// Use the define() function if we're in AMD land
+if (typeof define === 'function' && define.amd)
+  define(exports);
+
+})(
+  typeof exports === 'object' ? exports :
+  typeof define === 'function' && define.amd ? {} :
+  semver = {}
+);
diff --git a/lib/common/util.js b/lib/common/util.js
index 8158afce99df..ec27a6d09e77 100644
--- a/lib/common/util.js
+++ b/lib/common/util.js
@@ -183,6 +183,9 @@ module.exports.handleResp = handleResp;
  * @return {string}
  */
 function getType(value) {
+  if (value instanceof Buffer) {
+    return 'buffer';
+  }
   return Object.prototype.toString.call(value).match(/\s(\w+)\]/)[1];
 }
 
diff --git a/lib/index.js b/lib/index.js
index 530f42352d9c..3d01d7ca23cc 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -20,6 +20,12 @@
 
 'use strict';
 
+/**
+ * @type module:common/util
+ * @private
+ */
+var util = require('./common/util.js');
+
 /**
  * @type {module:datastore}
  * @private
@@ -30,7 +36,7 @@ var Datastore = require('./datastore');
  * @type {module:pubsub}
  * @private
  */
-var pubsub = require('./pubsub');
+var PubSub = require('./pubsub');
 
 /**
  * @type {module:storage}
@@ -86,13 +92,17 @@ var Storage = require('./storage');
  *
  * var bucket = gcloud.storage.bucket({
  *   bucketName: 'PhotosBucket',
- *   // properties may be overriden:
+ *   // properties may be overridden:
  *   keyFilename: '/path/to/other/keyfile.json'
  * });
  */
 function gcloud(config) {
   return {
     datastore: new Datastore(config),
+    pubsub: function(options) {
+      options = options || {};
+      return new PubSub(util.extendGlobalConfig(config, options));
+    },
     storage: new Storage(config)
   };
 }
@@ -130,24 +140,25 @@ gcloud.datastore = Datastore;
  * Note: Google Cloud Pub/Sub API is available as a Limited Preview and the
  * client library we provide is currently experimental. The API and/or the
  * client might be changed in backward-incompatible ways. This API is not
- * subject to any SLA or deprecation policy. Request to be whitelisted to use
- * it by filling the
+ * subject to any SLA or deprecation policy. Request to be whitelisted to use it
+ * by filling the
  * [Limited Preview application form]{@link http://goo.gl/sO0wTu}.
  *
  * @type {module:pubsub}
  *
- * @return {object}
+ * @return {module:pubsub}
  *
  * @example
  * var gcloud = require('gcloud');
- * var pubsub = gcloud.pubsub;
  *
- * var conn = new pubsub.Connection({
+ * var pubsub = gcloud.pubsub({
  *   projectId: YOUR_PROJECT_ID,
  *   keyFilename: '/path/to/the/key.json'
  * });
  */
-gcloud.pubsub = pubsub;
+gcloud.pubsub = function(config) {
+  return new PubSub(config);
+};
 
 /**
  * Google Cloud Storage allows you to store data on Google infrastructure.
@@ -171,7 +182,7 @@ gcloud.pubsub = pubsub;
  *
  * // storage:
  * // {
- * //   Bucket: function() {}
+ * //   bucket: function() {}
  * // }
  */
 gcloud.storage = Storage;
diff --git a/lib/pubsub/index.js b/lib/pubsub/index.js
index 31d67eec1e32..30d77e897ff6 100644
--- a/lib/pubsub/index.js
+++ b/lib/pubsub/index.js
@@ -1,4 +1,4 @@
-/**
+/*!
  * Copyright 2014 Google Inc. All Rights Reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -14,447 +14,287 @@
  * limitations under the License.
  */
 
-/**
+/*!
  * @module pubsub
  */
 
 'use strict';
 
-var events = require('events');
-var extend = require('extend');
-var nodeutil = require('util');
-
-/** @type {module:common/connection} */
-var conn = require('../common/connection.js');
-
-/** @type {module:common/util} */
-var util = require('../common/util.js');
-
-/** @private @const {string} Base URL for Pub/Sub API. */
-var PUBSUB_BASE_URL = 'https://www.googleapis.com/pubsub/v1beta1';
-
-/** @const {array} Required scopes for Pub/Sub API. */
-var SCOPES = [
-  'https://www.googleapis.com/auth/pubsub',
-  'https://www.googleapis.com/auth/cloud-platform'
-];
-
-function Subscription(conn, name) {
-  this.conn = conn;
-  this.name = name;
-
-  this.autoAck = false;
-  this.pullIntervalInMs = 10;
-  this.closed = false;
-}
-
-nodeutil.inherits(Subscription, events.EventEmitter);
-
-/**
- * Acknowledges the backend that message is retrieved.
- * @param  {Array<String>}  ids      A list of message IDs.
- * @param  {Function}       callback Callback function.
- */
-Subscription.prototype.ack = function(ids, callback) {
-  ids = util.arrayize(ids);
-  var body = {
-    subscription: this.name,
-    ackId: ids
-  };
-  this.conn.makeReq('POST', 'subscriptions/acknowledge', null, body, callback);
-};
-
-/**
- * Pulls from the subscribed topic.
- * @param  {Boolean}   opts.returnImmediately  If set, the system will respond
- *                                             immediately. Otherwise, wait
- *                                             until new messages are available.
- *                                             Returns if timeout is reached.
- * @param  {Function}  callback                Callback.
- */
-Subscription.prototype.pull = function(opts, callback) {
-  var that = this;
-  // TODO(jbd): Should not be racing with other pull.
-  // TOOD(jbd): Make opts optional.
-  var body = {
-    subscription: this.name,
-    returnImmediately: !!opts.returnImmediately
-  };
-  this.conn.makeReq(
-      'POST', 'subscriptions/pull', null, body, function(err, message) {
-    // TODO(jbd): Fix API to return a list of messages.
-    if (err) {
-      callback(err);
-      return;
-    }
-    if (!that.autoAck) {
-      that.emitMessage_(message);
-      callback();
-      return;
-    }
-    that.ack(message.ackId, function(err) {
-      if (err) {
-        callback(err);
-        return;
-      }
-      that.emitMessage_(message);
-      callback();
-    });
-  });
-};
-
-/**
- * Polls the backend for new messages.
- */
-Subscription.prototype.startPulling_ = function() {
-  var that = this;
-  var pullFn = function() {
-    if (that.closed) {
-      return;
-    }
-    that.pull({ returnImmediately: false }, function(err) {
-      // TODO(jbd): Fix API to return a more explicit error code or message.
-      if (err && err.message.indexOf('has no more messages') < 0) {
-        that.emitError_(err);
-      }
-      setTimeout(function() {
-        pullFn();
-      }, that.pullIntervalInMs);
-    });
-  };
-  pullFn();
-};
-
 /**
- * Deletes the current subscription. Pull requests from the current
- * subscription will be errored once unsubscription is done.
- * @param  {Function} callback Optional callback.
+ * @type module:common/connection
+ * @private
  */
-Subscription.prototype.del = function(callback) {
-  callback = callback || util.noop;
-  var that = this;
-  var path = util.format('subscriptions/{fullName}', {
-    fullName: this.name
-  });
-  this.conn.makeReq('DELETE', path, null, true, function(err) {
-    if (err) {
-      callback(err);
-      return;
-    }
-    that.closed = true;
-    callback(null);
-  });
-};
-
-/**
- * Closes the subscription.
- */
-Subscription.prototype.close = function() {
-  this.closed = true;
-};
-
-/**
- * Emits a 'message' event with the provided message.
- */
-Subscription.prototype.emitMessage_ = function(msg) {
-  if (msg.pubsubEvent && msg.pubsubEvent.message) {
-    var data = msg.pubsubEvent.message.data;
-    msg.pubsubEvent.message.data = new Buffer(data, 'base64').toString('utf-8');
-  }
-  this.emit('message', msg);
-};
+var conn = require('../common/connection.js');
 
 /**
- * Emits an error with the provided error.
+ * @type module:pubsub/subscription
+ * @private
  */
-Subscription.prototype.emitError_ = function(err) {
-  this.emit('error', err);
-};
+var Subscription = require('./subscription.js');
 
 /**
- * Represents a Google Cloud Pub/Sub API topic.
- * @param {Connection} conn  Authorized connection.
- * @param {string}     name  Full name of the topic.
+ * @type module:pubsub/topic
+ * @private
  */
-function Topic(conn, name) {
-  this.conn = conn;
-  this.name = name;
-}
+var Topic = require('./topic.js');
 
 /**
- * Publishes the provided string message.
- * @param  {string}   data         String message to publish.
- * @param  {Function} callback     Optional callback.
+ * @type module:common/util
+ * @private
  */
-Topic.prototype.publish = function(data, callback) {
-  callback = callback || util.noop;
-  this.publishMessage({
-    topic: this.name,
-    message: {
-      data: new Buffer(data).toString('base64')
-    }
-  }, callback);
-};
+var util = require('../common/util.js');
 
 /**
- * Publishes a raw message.
- * @param  {message}  message       Raw message to publish.
- * @param  {Function} callback      Optional callback.
+ * @const {string} Base URL for Pub/Sub API.
+ * @private
  */
-Topic.prototype.publishMessage = function(message, callback) {
-  callback = callback || util.noop;
-  message.topic = this.name;
-  this.conn.makeReq('POST', 'topics/publish', null, message, callback);
-};
+var PUBSUB_BASE_URL = 'https://www.googleapis.com/pubsub/v1beta1';
 
 /**
- * Deletes a topic.
- * @param  {Function} callback Optional callback.
+ * @const {array} Required scopes for Pub/Sub API.
+ * @private
  */
-Topic.prototype.del = function(callback) {
-  callback = callback || util.noop;
-  var path = 'topics/' + this.name;
-  this.conn.makeReq('DELETE', path, null, true, callback);
-};
+var SCOPES = [
+  'https://www.googleapis.com/auth/pubsub',
+  'https://www.googleapis.com/auth/cloud-platform'
+];
 
 /**
- * Represents connection to Google Cloud Pub/Sub API.
- * @param {string} opts.projectId   Google Developers Console Project ID.
- * @param {string} opts.email       Service account email.
+ * **Experimental**
+ *
+ * [Google Cloud Pub/Sub]{@link https://developers.google.com/pubsub/overview}
+ * is a reliable, many-to-many, asynchronous messaging service from Google
+ * Cloud Platform.
+ *
+ * Note: Google Cloud Pub/Sub API is available as a Limited Preview and the
+ * client library we provide is currently experimental. The API and/or the
+ * client might be changed in backward-incompatible ways. This API is not
+ * subject to any SLA or deprecation policy. Request to be whitelisted to use
+ * it by filling the
+ * [Limited Preview application form]{@link http://goo.gl/sO0wTu}.
+ *
+ * @constructor
+ * @alias module:pubsub
+ *
+ * @param {object=} options - Configuration object.
+ * @param {string=} options.projectId - Google Developers Console Project ID.
  * @param {string=} options.keyFilename - Full path to the JSON key downloaded
  *     from the Google Developers Console. Alternatively, you may provide a
  *     `credentials` object.
  * @param {object=} options.credentials - Credentials object, used in place of
  *     a `keyFilename`.
+ *
+ * @example
+ * var gcloud = require('gcloud');
+ *
+ * // From Google Compute Engine and Google App Engine:
+ *
+ * // Access `pubsub` through the `gcloud` module directly.
+ * var pubsub = gcloud.pubsub();
+ *
+ * // Elsewhere:
+ *
+ * // Provide configuration details up-front.
+ * var myProject = gcloud({
+ *   keyFilename: '/path/to/keyfile.json',
+ *   projectId: 'my-project'
+ * });
+ *
+ * var pubsub = myProject.pubsub();
+ *
+ *
+ * // Override default configuration details.
+ * var anotherPubsubConnection = myProject.pubsub({
+ *   keyFilename: '/path/to/another/keyfile.json',
+ * });
+ *
+ *
+ * // Specify all options at instantiation.
+ * var pubsub = gcloud.pubsub({
+ *   keyFilename: '/path/to/keyfile.json',
+ *   projectId: 'my-project'
+ * });
  */
-function Connection(opts) {
-  opts = opts || {};
-  var id = opts.projectId;
+function PubSub(options) {
+  options = options || {};
 
-  this.id = id;
-  this.conn = new conn.Connection({
-    credentials: opts.credentials,
-    keyFilename: opts.keyFilename,
+  this.connection = new conn.Connection({
+    credentials: options.credentials,
+    keyFilename: options.keyFilename,
     scopes: SCOPES
   });
+  this.projectId = options.projectId;
+  this.projectName = '/projects/' + this.projectId;
 }
 
 /**
- * Lists subscriptions.
- * @param  {string}   query.filterByTopic Returns subscriptions that are
- *                                        subscribed to the topic provided.
- * @param  {string}   query.pageToken     Page token.
- * @param  {Number}   query.maxResults    Max number of results to return.
- * @param  {Function} callback            Callback function.
+ * Get a list of the topics registered to your project. You may optionally
+ * provide a query object as the first argument to customize the response.
+ *
+ * @param {object=} query - Query object.
+ * @param {string=} query.pageToken - Page token.
+ * @param {number=} query.maxResults - Maximum number of results to return.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * // Get all topics.
+ * pubsub.getTopics(function(err, topics, nextQuery) {
+ *   // If `nextQuery` is non-null, there may be more results to fetch. To do
+ *   // so, run `pubsub.getTopics(nextQuery, callback);`.
+ * });
+ *
+ * // Customize the query.
+ * pubsub.getTopics({
+ *   maxResults: 3
+ * }, function(err, topics, nextQuery) {});
  */
-Connection.prototype.listSubscriptions = function(query, callback) {
+PubSub.prototype.getTopics = function(query, callback) {
   var that = this;
-  if (arguments.length < 2) {
+  if (!callback) {
     callback = query;
     query = {};
   }
-  var q = extend({}, query);
-  if (q.filterByTopic) {
-    q.query =
-        'pubsub.googleapis.com/topic in (' +
-        this.fullTopicName_(q.filterByTopic) + ')';
-  } else {
-    q.query =
-        'cloud.googleapis.com/project in (' + this.fullProjectName_() + ')';
-  }
-  delete q.filterByTopic;
-
-  this.makeReq('GET', 'subscriptions', q, true, function(err, result) {
+  query.query = 'cloud.googleapis.com/project in (' + this.projectName + ')';
+  this.makeReq_('GET', 'topics', query, true, function(err, result) {
     if (err) {
       callback(err);
       return;
     }
-    var items = result.subscription || [];
-    var subscriptions = items.map(function(item) {
-      return new Subscription(that, item.name);
+    var topics = (result.topic || []).map(function(item) {
+      return new Topic(that, {
+        name: item.name
+      });
     });
     var nextQuery = null;
     if (result.nextPageToken) {
-      nextQuery = q;
+      nextQuery = query;
       nextQuery.pageToken = result.nextPageToken;
     }
-    callback(null, subscriptions, nextQuery);
+    callback(null, topics, nextQuery);
   });
 };
 
 /**
- * Gets a subscription.
- * @param  {string}   name     Name of the subscription.
- * @param  {Function} callback Callback.
+ * Create a topic with the given name.
+ *
+ * @param {string} name - Name of the topic.
+ * @param {function=} callback - The callback function.
+ *
+ * @example
+ * pubsub.createTopic('my-new-topic', function(err, topic) {
+ *   topic.publish('New message!', function(err) {});
+ * });
  */
-Connection.prototype.getSubscription = function(name, callback) {
-  var that = this;
-  var fullName = '/subscriptions/' + this.id + '/' + name;
-  this.makeReq('GET', 'subscriptions/' + fullName, null, true, function(err) {
-    if (err) {
-      callback(err);
-      return;
-    }
-    callback(null, new Subscription(that, fullName));
-  });
-};
-
-Connection.prototype.createSubscription = function(opts, callback) {
-  var that = this;
-  var subscription = {
-    topic:'/topics/' + this.id + '/' + opts.topic,
-    name: '/subscriptions/' + this.id + '/' + opts.name,
-    ackDeadlineSeconds: opts.ackDeadlineSeconds
+PubSub.prototype.createTopic = function(name, callback) {
+  callback = callback || util.noop;
+  var topic = this.topic(name);
+  var req = {
+    name: topic.name
   };
-  this.makeReq('POST', 'subscriptions', null, subscription, function(err) {
+  this.makeReq_('POST', 'topics', null, req, function(err) {
     if (err) {
       callback(err);
       return;
     }
-    callback(null, new Subscription(that, subscription.name));
-  });
+    callback(null, topic);
+  }.bind(this));
 };
 
 /**
- * Subscribe with the provided options.
- * @param  {string}   name           Name of the subscription.
- * @param  {Boolean}  opts.autoAck   Automatically acknowledges the
- *                                   message once it's pulled.
- * @return {Subscription}
+ * Create a Topic object to reference an existing topic.
+ *
+ * @throws {Error} If a name is not provided.
+ *
+ * @param {string} name - The name of the topic.
+ * @return {module:pubsub/topic}
+ *
+ * @example
+ * var topic = pubsub.topic('my-existing-topic');
+ * topic.publish('New message!');
  */
-Connection.prototype.subscribe = function(name, opts) {
-  opts = opts || {};
-
-  var fullName = '/subscriptions/' + this.id + '/' + name;
-  var sub = new Subscription(this, fullName);
-  sub.autoAck = !!opts.autoAck;
-  this.getSubscription(name, function(err) {
-    if (err) {
-      sub.emitError_(err);
-      return;
-    }
-    sub.emit('ready');
-    sub.startPulling_();
+PubSub.prototype.topic = function(name) {
+  if (!name) {
+    throw new Error('A name must be specified for a new topic.');
+  }
+  return new Topic(this, {
+    name: name
   });
-  return sub;
 };
 
 /**
- * Lists topics.
- * @param  {string}   query.pageToken     Page token.
- * @param  {Number}   query.maxResults    Max number of results to return.
- * @param  {Function} callback            Callback function.
+ * Get a list of the subscriptions registered to all of your project's topics.
+ * You may optionally provide a query object as the first argument to customize
+ * the response.
+ *
+ * @param {object=} query - Query object.
+ * @param {string=} query.pageToken - Page token.
+ * @param {number=} query.maxResults - Maximum number of results to return.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * // Get all subscriptions.
+ * pubsub.getSubscriptions(function(err, subscriptions, nextQuery) {
+ *   // If `nextQuery` is non-null, there may be more results to fetch. To do
+ *   // so, run `pubsub.getSubscriptions(nextQuery, callback);`.
+ * });
+ *
+ * // Customize the query.
+ * pubsub.getSubscriptions({
+ *   maxResults: 10
+ * }, function(err, subscriptions, nextQuery) {});
  */
-Connection.prototype.listTopics = function(query, callback) {
+PubSub.prototype.getSubscriptions = function(query, callback) {
   var that = this;
-  if (arguments.length < 2) {
+  if (!callback) {
     callback = query;
     query = {};
   }
-  var q = extend({}, query);
-  q.query = 'cloud.googleapis.com/project in (' + this.fullProjectName_() + ')';
-  this.makeReq('GET', 'topics', q, true, function(err, result) {
+  if (!query.query) {
+    query.query = 'cloud.googleapis.com/project in (' + this.projectName + ')';
+  }
+  this.makeReq_('GET', 'subscriptions', query, true, function(err, result) {
     if (err) {
       callback(err);
       return;
     }
-    var items = result.topic || [];
-    var topics = items.map(function(item) {
-      return new Topic(that, item.name);
+    var subscriptions = (result.subscription || []).map(function(item) {
+      return new Subscription(that, {
+        name: item.name
+      });
     });
     var nextQuery = null;
     if (result.nextPageToken) {
-      nextQuery = q;
+      nextQuery = query;
       nextQuery.pageToken = result.nextPageToken;
     }
-    callback(null, topics, nextQuery);
-  });
-};
-
-/**
- * Gets a topic.
- * @param  {string}   name         Name of the topic to get.
- * @param  {Function} callback     Optional callback.
- */
-Connection.prototype.getTopic = function(name, callback) {
-  var that = this;
-  callback = callback || util.noop;
-  var fullName = this.fullTopicName_(name);
-  this.makeReq('GET', 'topics/' + fullName, null, true, function(err) {
-    if (err) {
-      callback(err);
-      return;
-    }
-    callback(null, new Topic(that, fullName));
-  });
-};
-
-/**
- * Creates a topic with the given name.
- * @param  {string}   name         Name of the topic.
- * @param  {Function} callback     Optional callback.
- */
-Connection.prototype.createTopic = function(name, callback) {
-  var that = this;
-  callback = callback || util.noop;
-  var fullName = this.fullTopicName_(name);
-  this.makeReq('POST', 'topics', null, { name: fullName }, function(err) {
-    if (err) {
-      callback(err);
-      return;
-    }
-    callback(null, new Topic(that, fullName));
-  });
-};
-
-/**
- * Returns the full name of a topic.
- * Full name is in /topics/<projectId>/<shortName> form.
- */
-Connection.prototype.fullTopicName_ = function(name) {
-  return util.format('/topics/{projectId}/{name}', {
-    projectId: this.id, name: name
+    callback(null, subscriptions, nextQuery);
   });
 };
 
 /**
- * Returns the fully qualified project name.
- * Full name is in /projects/<projectId> form.
+ * Make a new request object from the provided arguments and wrap the callback
+ * to intercept non-successful responses.
+ *
+ * @private
+ *
+ * @param {string} method - Action.
+ * @param {string} path - Request path.
+ * @param {*} query - Request query object.
+ * @param {*} body - Request body contents.
+ * @param {function} callback - The callback function.
  */
-Connection.prototype.fullProjectName_ = function() {
-  return util.format('/projects/{projectId}', {
-    projectId: this.id
-  });
-};
-
-Connection.prototype.makeReq = function(method, path, q, body, callback) {
+PubSub.prototype.makeReq_ = function(method, path, q, body, callback) {
   var reqOpts = {
     method: method,
     qs: q,
-    uri: util.format('{base}/{path}', {
-      base: PUBSUB_BASE_URL,
-      path: path
-    })
+    uri: PUBSUB_BASE_URL + '/' + path
   };
   if (body) {
     reqOpts.json = body;
   }
-  this.conn.req(reqOpts, function(err, res, body) {
+  this.connection.req(reqOpts, function(err, res, body) {
     util.handleResp(err, res, body, callback);
   });
 };
 
-/**
- * Exports Connection.
- */
-module.exports.Connection = Connection;
-
-/**
- * Exports Topic.
- */
-module.exports.Topic = Topic;
-
-/**
- * Exports Subscription.
- */
-module.exports.Subscription = Subscription;
+module.exports = PubSub;
diff --git a/lib/pubsub/subscription.js b/lib/pubsub/subscription.js
new file mode 100644
index 000000000000..74aeae250c57
--- /dev/null
+++ b/lib/pubsub/subscription.js
@@ -0,0 +1,327 @@
+/*!
+ * Copyright 2014 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*!
+ * @module pubsub/subscription
+ */
+
+'use strict';
+
+var events = require('events');
+var nodeutil = require('util');
+
+/**
+ * @type module:common/util
+ * @private
+ */
+var util = require('../common/util.js');
+
+/*! Developer Documentation
+ *
+ * @param {module:pubsub} pubsub - PubSub object.
+ * @param {object} options - Configuration object.
+ * @param {boolean} options.autoAck - Automatically acknowledge the message
+ *     once it's pulled. (default: false)
+ * @param {number} options.interval - Interval in milliseconds to check for new
+ *     messages. (default: 10)
+ * @param {string} options.name - Name of the subscription.
+ */
+/**
+ * A Subscription object will give you access to your Google Cloud Pub/Sub
+ * subscription.
+ *
+ * Subscriptions are sometimes retrieved when using various methods:
+ *
+ * - {@linkcode module:pubsub#getSubscriptions}
+ * - {@linkcode module:pubsub/topic#getSubscriptions}
+ * - {@linkcode module:pubsub/topic#subscribe}
+ *
+ * Subscription objects may be created directly with:
+ *
+ * - {@linkcode module:pubsub/topic#subscription}
+ *
+ * A subscription won't begin pulling for messages until you register an event
+ * listener. See below for an example.
+ *
+ * @alias pubsub/subscription
+ * @constructor
+ *
+ * @example
+ * //-
+ * // From {@linkcode module:pubsub#getSubscriptions}:
+ * //-
+ * pubsub.getSubscriptions(function(err, subscriptions) {
+ *   // `subscriptions` is an array of Subscription objects.
+ * });
+ *
+ * //-
+ * // From {@linkcode module:pubsub/topic#getSubscriptions}:
+ * //-
+ * var topic = pubsub.topic('my-existing-topic');
+ * topic.getSubscriptions(function(err, subscriptions) {
+ *   // `subscriptions` is an array of Subscription objects.
+ * });
+ *
+ * //-
+ * // From {@linkcode module:pubsub/topic#subscribe}:
+ * //-
+ * var topic = pubsub.topic('my-existing-topic');
+ * topic.subscribe('new-subscrpition', function(err, subscription) {
+ *   // `subscription` is a Subscription object.
+ * });
+ *
+ * //-
+ * // From {@linkcode module:pubsub/topic#subscription}:
+ * //-
+ * var topic = pubsub.topic('my-existing-topic');
+ * var subscription = topic.subscription('my-existing-subscription');
+ * // `subscription` is a Subscription object.
+ *
+ * //-
+ * // Once you have obtained a subscription object, you may begin to register
+ * // listeners. This will automatically trigger pulling for messages.
+ * //-
+ * // Register an error handler.
+ * subscription.on('error', function(err) {});
+ *
+ * // Register a listener for `message` events.
+ * function onMessage(message) {
+ *   // Called every time a message is received.
+ *   // message.id = ID used to acknowledge its receival.
+ *   // message.data = Contents of the message.
+ * }
+ * subscription.on('message', onMessage);
+ *
+ * // Remove the listener from receiving `message` events.
+ * subscription.removeListener('message', onMessage);
+ */
+function Subscription(pubsub, options) {
+  events.EventEmitter.call(this);
+
+  this.name = Subscription.formatName_(pubsub.projectId, options.name);
+  this.makeReq_ = pubsub.makeReq_.bind(pubsub);
+
+  this.autoAck = util.is(options.autoAck, 'boolean') ? options.autoAck : false;
+  this.closed = false;
+  this.interval = util.is(options.interval, 'number') ? options.interval : 10;
+
+  this.listenForEvents_();
+}
+
+nodeutil.inherits(Subscription, events.EventEmitter);
+
+/**
+ * Format the name of a subscription. A subscription's full name is in the
+ * format of /subscription/{projectId}/{name}.
+ *
+ * @private
+ */
+Subscription.formatName_ = function(projectId, name) {
+  // Simple check if the name is already formatted.
+  if (name.indexOf('/') > -1) {
+    return name;
+  }
+  return '/subscriptions/' + projectId + '/' + name;
+};
+
+/**
+ * Simplify a message from an API response to have two properties, `id` and
+ * `data`. `data` is always converted to a string.
+ *
+ * @private
+ */
+Subscription.formatMessage_ = function(msg) {
+  var message = {
+    id: msg.ackId
+  };
+  if (msg.pubsubEvent && msg.pubsubEvent.message) {
+    message.data =
+      new Buffer(msg.pubsubEvent.message.data, 'base64').toString('utf-8');
+    try {
+      message.data = JSON.parse(message.data);
+    } catch(e) {}
+  }
+  return message;
+};
+
+/**
+ * Begin listening for events on the subscription. This method keeps track of
+ * how many message listeners are assigned, and then removed, making sure
+ * polling is handled automatically.
+ *
+ * As long as there is one active message listener, the connection is open. As
+ * soon as there are no more message listeners, the connection is closed.
+ *
+ * @private
+ *
+ * @example
+ * this.listenForEvents_();
+ */
+Subscription.prototype.listenForEvents_ = function() {
+  var that = this;
+  var messageListeners = 0;
+
+  this.on('newListener', function(event) {
+    if (event === 'message') {
+      messageListeners++;
+      if (that.closed) {
+        that.closed = false;
+      }
+      that.startPulling_();
+    }
+  });
+
+  this.on('removeListener', function(event) {
+    if (event === 'message' && --messageListeners === 0) {
+      that.closed = true;
+    }
+  });
+};
+
+/**
+ * Poll the backend for new messages. This runs a loop to ping the API at the
+ * provided interval from the subscription's instantiation. If one wasn't
+ * provided, the default value is 10 milliseconds.
+ *
+ * If messages are received, they are emitted on the `message` event.
+ *
+ * Note: This method is automatically called once a message event handler is
+ * assigned to the description.
+ *
+ * To stop pulling, see {@linkcode module:pubsub/subscription#close}.
+ *
+ * @private
+ *
+ * @example
+ * subscription.startPulling_();
+ */
+Subscription.prototype.startPulling_ = function() {
+  var that = this;
+  if (this.closed) {
+    return;
+  }
+  this.pull({
+    returnImmediately: false
+  }, function(err, message) {
+    if (err) {
+      that.emit('error', err);
+    }
+    if (message) {
+      that.emit('message', message);
+    }
+    setTimeout(that.startPulling_.bind(that), that.interval);
+  });
+};
+
+/**
+ * Acknowledge to the backend that the message was retrieved. You must provide
+ * either a single ID, or an array of IDs.
+ *
+ * @throws {Error} If at least one id is not provided.
+ *
+ * @param {string|string[]} ids - An ID or array of message IDs.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * subscription.ack('ePHEESyhuE8e...', function(err) {});
+ */
+Subscription.prototype.ack = function(ids, callback) {
+  if (!ids || ids.length === 0) {
+    throw new Error(
+        'At least one ID must be specified before it can be acknowledged');
+  }
+  ids = util.arrayize(ids);
+  var body = {
+    subscription: this.name,
+    ackId: ids
+  };
+  this.makeReq_('POST', 'subscriptions/acknowledge', null, body, callback);
+};
+
+/**
+ * Delete the subscription. Pull requests from the current subscription will be
+ * errored once unsubscription is complete.
+ *
+ * @param {function=} callback - The callback function.
+ *
+ * @example
+ * subscription.delete(function(err) {});
+ */
+Subscription.prototype.delete = function(callback) {
+  callback = callback || util.noop;
+  this.makeReq_(
+      'DELETE', 'subscriptions/' + this.name, null, true, function(err) {
+    if (err) {
+      callback(err);
+      return;
+    }
+    this.closed = true;
+    this.removeAllListeners();
+    callback(null);
+  }.bind(this));
+};
+
+/**
+ * Pull messages from the subscribed topic. If messages were found, your
+ * callback is executed with the message object.
+ *
+ * Note that messages are pulled automatically once you register your first
+ * event listener to the subscription, thus the call to `pull` is handled for
+ * you. If you don't want to start pulling, simply don't register a
+ * `subscription.on('message', function() {})` event handler.
+ *
+ * @param {object=} options - Configuration object.
+ * @param {boolean=} options.returnImmediately - If set, the system will respond
+ *     immediately. Otherwise, wait until new messages are available. Returns if
+ *     timeout is reached.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * subscription.pull(function(err, message) {
+ *   // message.id = ID used to acknowledge its receival.
+ *   // message.data = Contents of the message.
+ * });
+ */
+Subscription.prototype.pull = function(options, callback) {
+  var that = this;
+  // TODO(jbd): Should not be racing with other pull.
+  if (!callback) {
+    callback = options;
+    options = {};
+  }
+  var body = {
+    subscription: this.name,
+    returnImmediately: !!options.returnImmediately
+  };
+  this.makeReq_(
+      'POST', 'subscriptions/pull', null, body, function(err, message) {
+    // TODO(jbd): Fix API to return a list of messages.
+    if (err) {
+      callback(err);
+      return;
+    }
+    message = Subscription.formatMessage_(message);
+    if (that.autoAck) {
+      that.ack(message.id, function(err) {
+        callback(err, message);
+      });
+    } else {
+      callback(null, message);
+    }
+  });
+};
+
+module.exports = Subscription;
diff --git a/lib/pubsub/topic.js b/lib/pubsub/topic.js
new file mode 100644
index 000000000000..53ced5ac5072
--- /dev/null
+++ b/lib/pubsub/topic.js
@@ -0,0 +1,270 @@
+/*!
+ * Copyright 2014 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*!
+ * @module pubsub/topic
+ */
+
+'use strict';
+
+/**
+ * @type module:common/util
+ * @private
+ */
+var util = require('../common/util.js');
+
+/**
+ * @type module:pubsub/subscription
+ * @private
+ */
+var Subscription = require('./subscription.js');
+
+/*! Developer Documentation
+ *
+ * @param {module:pubsub} pubsub - PubSub object.
+ * @param {object} options - Configuration object.
+ * @param {string} options.name - Name of the topic.
+ */
+/**
+ * A Topic object allows you to interact with a Google Cloud Pub/Sub topic. To
+ * get this object, you will use the methods on the `pubsub` object,
+ * {@linkcode module:pubsub#topic} and {@linkcode module:pubsub#createTopic}.
+ *
+ * @constructor
+ * @alias module:pubsub/topic
+ *
+ * @example
+ * // From pubsub.topic:
+ * var topic = pubsub.topic('my-existing-topic');
+ *
+ * // From pubsub.createTopic:
+ * pubsub.createTopic('my-new-topic', function(err, topic) {
+ *   // `topic` is a Topic object.
+ * });
+ */
+function Topic(pubsub, options) {
+  this.makeReq_ = pubsub.makeReq_.bind(pubsub);
+  this.name = Topic.formatName_(pubsub.projectId, options.name);
+  this.projectId = pubsub.projectId;
+  this.pubsub = pubsub;
+}
+
+/**
+ * Format the name of a topic. A Topic's full name is in the format of
+ * /topics/{projectId}/{name}.
+ *
+ * @private
+ *
+ * @return {string}
+ */
+Topic.formatName_ = function(projectId, name) {
+  // Simple check if the name is already formatted.
+  if (name.indexOf('/') > -1) {
+    return name;
+  }
+  return '/topics/' + projectId + '/' + name;
+};
+
+/**
+ * Publish the provided message. A message can be of any type.
+ *
+ * @throws {Error} If no message is provided.
+ *
+ * @param {*} message - The message to publish.
+ * @param {function=} callback - The callback function.
+ *
+ * @example
+ * topic.publish('New message!', function(err) {});
+ *
+ * topic.publish({
+ *   user_id: 3,
+ *   name: 'Stephen',
+ *   message: 'Hello from me!'
+ * }, function(err) {});
+ */
+Topic.prototype.publish = function(message, callback) {
+  if (!message) {
+    throw new Error('Cannot publish an empty message.');
+  }
+  callback = callback || util.noop;
+  if (!util.is(message, 'string') && !util.is(message, 'buffer')) {
+    message = JSON.stringify(message);
+  }
+  this.publishRaw({
+    data: new Buffer(message).toString('base64')
+  }, callback);
+};
+
+/**
+ * Publish a raw message.
+ *
+ * @throws {Error} If no message is provided.
+ *
+ * @param {object} message - Raw message to publish.
+ * @param {array=} message.label - List of labels for the message.
+ * @param {*} message.data - The contents of the message.
+ * @param {function=} callback - The callback function.
+ *
+ * @example
+ * topic.publishRaw({
+ *   data: new Buffer('New message!').toString('base64')
+ * }, function(err) {});
+ */
+Topic.prototype.publishRaw = function(message, callback) {
+  if (!message) {
+    throw new Error('Cannot publish an empty message.');
+  }
+  callback = callback || util.noop;
+  if (!util.is(message.data, 'string') && !util.is(message.data, 'buffer')) {
+    message.data = new Buffer(JSON.stringify(message.data)).toString('base64');
+  }
+  message.topic = this.name;
+  this.makeReq_('POST', 'topics/publish', null, message, callback);
+};
+
+/**
+ * Delete the topic.
+ *
+ * @param {function=} callback - The callback function.
+ *
+ * @example
+ * topic.delete(function(err) {});
+ */
+Topic.prototype.delete = function(callback) {
+  callback = callback || util.noop;
+  this.makeReq_('DELETE', 'topics/' + this.name, null, true, callback);
+};
+
+/**
+ * Get a list of the subscriptions registered to this topic. You may optionally
+ * provide a query object as the first argument to customize the response.
+ *
+ * Your provided callback will either be invoked with an error object, if an API
+ * error occurred, or an array of {@linkcode module:pubsub/subscription}
+ * objects.
+ *
+ * @param {object=} query - Query object.
+ * @param {string=} query.pageToken - Page token.
+ * @param {number=} query.maxResults - Maximum number of results to return.
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * // Get all subscriptions.
+ * topic.getSubscriptions(function(err, subscriptions, nextQuery) {
+ *   // If `nextQuery` is non-null, there may be more results to fetch. To do
+ *   // so, run `topic.getSubscriptions(nextQuery, callback);`.
+ * });
+ *
+ * // Customize the query.
+ * topic.getSubscriptions({
+ *   maxResults: 3
+ * }, function(err, subscriptions, nextQuery) {});
+ */
+Topic.prototype.getSubscriptions = function(query, callback) {
+  query.query = 'pubsub.googleapis.com/topic in (' + this.name + ')';
+  this.pubsub.getSubscriptions(query, callback);
+};
+
+/**
+ * Create a subscription to this topic. You may optionally provide an object to
+ * customize the subscription.
+ *
+ * Your provided callback will either be invoked with an error object, if an API
+ * error occurred, or a {@linkcode module:pubsub/subscription} object.
+ *
+ * @throws {Error} If a name is not provided.
+ *
+ * @param {string} name - The name of the subscription.
+ * @param {object=} options - Configuration object.
+ * @param {number=} options.ackDeadlineSeconds - The maximum time after
+ *     receiving a message that you must ack a message before it is redelivered.
+ * @param {boolean=} options.autoAck - Automatically acknowledge the message
+ *     once it's pulled. (default: false)
+ * @param {number=} options.interval - Interval in milliseconds to check for new
+ *     messages. (default: 10)
+ * @param {function} callback - The callback function.
+ *
+ * @example
+ * // Without specifying any options.
+ * topic.subscribe('new-subscription', function(err, subscription) {});
+ *
+ * // With options.
+ * topic.subscribe('new-subscription', {
+ *   ackDeadlineSeconds: 90,
+ *   autoAck: true,
+ *   interval: 30
+ * }, function(err, subscription) {});
+ */
+Topic.prototype.subscribe = function(name, options, callback) {
+  if (!name) {
+    throw new Error('A name is required for a new subscription.');
+  }
+  if (!callback) {
+    callback = options;
+    options = {};
+  }
+  var body = {
+    topic: this.name,
+    name: Subscription.formatName_(this.projectId, name)
+  };
+  if (options.ackDeadlineSeconds) {
+    body.ackDeadlineSeconds = options.ackDeadlineSeconds;
+  }
+  this.makeReq_('POST', 'subscriptions', null, body, function(err) {
+    if (err) {
+      callback(err);
+      return;
+    }
+    callback(null, this.subscription(name, options));
+  }.bind(this));
+};
+
+/**
+ * Create a Subscription object in reference to an existing subscription. This
+ * command by itself will not run any API requests. You will receive a
+ * {@linkcode module:pubsub/subscription} object, which will allow you to
+ * interact with your subscription.
+ *
+ * @throws {Error} If a name is not provided.
+ *
+ * @param {string} name - Name of the subscription.
+ * @param {object=} options - Configuration object.
+ * @param {boolean=} options.autoAck - Automatically acknowledge the message
+ *     once it's pulled.
+ * @param {number=} options.interval - Interval in milliseconds to check for new
+ *     messages.
+ * @return {module:pubsub/subscription}
+ *
+ * @example
+ * var subscription = topic.subscription('my-existing-subscription');
+ *
+ * // Register a listener for `message` events.
+ * subscription.on('message', function(message) {
+ *   // Called every time a message is received.
+ *   // message.id = ID used to acknowledge its receival.
+ *   // message.data = Contents of the message.
+ * });
+ */
+Topic.prototype.subscription = function(name, options) {
+  if (!name) {
+    throw new Error('The name of a subscription is required.');
+  }
+  options = options || {};
+  options.name = name;
+  return new Subscription(this.pubsub, options);
+};
+
+module.exports = Topic;
diff --git a/npm-debug.log b/npm-debug.log
new file mode 100644
index 000000000000..5300ae6d3ddc
--- /dev/null
+++ b/npm-debug.log
@@ -0,0 +1,33 @@
+0 info it worked if it ends with ok
+1 verbose cli [ 'node', '/Users/stephen/.nvm/v0.10.31/bin/npm', 'run', 'lint' ]
+2 info using npm@2.0.0
+3 info using node@v0.10.31
+4 verbose run-script [ 'prelint', 'lint', 'postlint' ]
+5 info prelint gcloud@0.7.1
+6 info lint gcloud@0.7.1
+7 verbose unsafe-perm in lifecycle true
+8 info gcloud@0.7.1 Failed to exec lint script
+9 verbose stack Error: gcloud@0.7.1 lint: `jshint lib/ regression/ test/`
+9 verbose stack Exit status 2
+9 verbose stack     at ChildProcess.<anonymous> (/Users/stephen/.nvm/v0.10.31/lib/node_modules/npm/lib/utils/lifecycle.js:212:16)
+9 verbose stack     at ChildProcess.emit (events.js:98:17)
+9 verbose stack     at maybeClose (child_process.js:756:16)
+9 verbose stack     at Process.ChildProcess._handle.onexit (child_process.js:823:5)
+10 verbose pkgid gcloud@0.7.1
+11 verbose cwd /Users/stephen/dev/gcloud-node
+12 error Darwin 13.4.0
+13 error argv "node" "/Users/stephen/.nvm/v0.10.31/bin/npm" "run" "lint"
+14 error node v0.10.31
+15 error npm  v2.0.0
+16 error code ELIFECYCLE
+17 error gcloud@0.7.1 lint: `jshint lib/ regression/ test/`
+17 error Exit status 2
+18 error Failed at the gcloud@0.7.1 lint script.
+18 error This is most likely a problem with the gcloud package,
+18 error not with npm itself.
+18 error Tell the author that this fails on your system:
+18 error     jshint lib/ regression/ test/
+18 error You can get their info via:
+18 error     npm owner ls gcloud
+18 error There is likely additional logging output above.
+19 verbose exit [ 1, true ]
diff --git a/package.json b/package.json
index 13b7540b15fe..ede031b2c7c5 100644
--- a/package.json
+++ b/package.json
@@ -63,12 +63,12 @@
     "tmp": "0.0.24"
   },
   "scripts": {
-    "docs": "dox < lib/index.js > docs/json/master/index.json & dox < lib/datastore/dataset.js > docs/json/master/datastore/dataset.json & dox < lib/datastore/index.js > docs/json/master/datastore/index.json & dox < lib/datastore/query.js > docs/json/master/datastore/query.json & dox < lib/storage/index.js > docs/json/master/storage/index.json",
+    "docs": "./scripts/docs.sh",
     "lint": "jshint lib/ regression/ test/",
     "test": "mocha --recursive --reporter spec",
-    "regression-test": "mocha regression/datastore.js regression/storage.js --reporter spec --timeout 15000",
-    "cover": "istanbul cover -x 'regression/* lib/pubsub/*' _mocha -- --timeout 15000 test/* regression/datastore.js regression/storage.js",
-    "coveralls": "istanbul cover -x 'regression/* lib/pubsub/*' _mocha --report lcovonly -- --timeout 15000 test/* regression/datastore.js regression/storage.js -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage"
+    "regression-test": "mocha regression/datastore.js regression/pubsub.js regression/storage.js --reporter spec --timeout 15000",
+    "cover": "istanbul cover -x 'regression/*' _mocha -- --timeout 15000 test/* regression/datastore.js regression/pubsub.js regression/storage.js",
+    "coveralls": "istanbul cover -x 'regression/*' _mocha --report lcovonly -- --timeout 15000 test/* regression/datastore.js regression/pubsub.js regression/storage.js -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage"
   },
   "license": "Apache 2"
 }
diff --git a/regression/pubsub.js b/regression/pubsub.js
index d0dea40566d2..c230fe97bb52 100644
--- a/regression/pubsub.js
+++ b/regression/pubsub.js
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-/*global describe, it, before */
+/*global describe, it, before, after */
 
 'use strict';
 
@@ -22,148 +22,168 @@ var assert = require('assert');
 var async = require('async');
 
 var env = require('./env.js');
-var gcloud = require('../lib');
-
-var topicNames = ['topic1', 'topic2', 'topic3'];
-var subscriptions = [
-  {
-    name: 'sub1',
-    ackDeadlineSeconds: 30
-  },
-  {
-    name: 'sub2',
-    ackDeadlineSeconds: 60
-  }
-];
+var gcloud = require('../lib')(env);
+
+var Subscription = require('../lib/pubsub/subscription.js');
 
-var conn = new gcloud.pubsub.Connection(env);
+var pubsub = gcloud.pubsub();
 
 describe('pubsub', function() {
+  var topicNames = ['topic1', 'topic2', 'topic3'];
 
-  before(function(done) {
+  function deleteAllTopics(callback) {
     // TODO: Handle pagination.
-    var createFn = function(name, callback) {
-      conn.createTopic(name, callback);
-    };
-    conn.listTopics(function(err, topics) {
+    pubsub.getTopics(function(err, topics) {
+      if (err) {
+        callback(err);
+        return;
+      }
+      async.parallel(topics.map(function(topic) {
+        return topic.delete.bind(topic);
+      }), callback);
+    });
+  }
+
+  before(function(done) {
+    deleteAllTopics(function(err) {
       assert.ifError(err);
-      var fns = topics.map(function(t) {
-        return function(cb) {
-          t.del(cb);
-        };
-      });
-      async.parallel(fns, function(err) {
-        assert.ifError(err);
-        async.map(topicNames, createFn, done);
-      });
+      // Create new topics.
+      async.map(topicNames, pubsub.createTopic.bind(pubsub), done);
     });
   });
 
+  after(deleteAllTopics);
+
   describe('Topic', function() {
     it('should be listed', function(done) {
-      conn.listTopics(function(err, topics) {
-        assert(topics.length, 3);
-        done(err);
+      pubsub.getTopics(function(err, topics) {
+        assert.ifError(err);
+        assert(topics.length, topicNames.length);
+        done();
       });
     });
 
     it('should return a nextQuery if there are more results', function(done) {
-      conn.listTopics({ maxResults: 2 }, function(err, topics, next) {
-        assert(topics.length, 2);
-        assert(next.maxResults, 2);
+      pubsub.getTopics({
+        maxResults: topicNames.length - 1
+      }, function(err, topics, next) {
+        assert.ifError(err);
+        assert(topics.length, topicNames.length - 1);
+        assert(next.maxResults, topicNames.length - 1);
         assert(!!next.pageToken, true);
-        done(err);
+        done();
       });
     });
 
     it('should be created', function(done) {
-      conn.createTopic('topic-new', done);
-    });
-
-    it('should be gettable', function(done) {
-      conn.getTopic('topic1', done);
+      pubsub.createTopic('new-topic-name', done);
     });
 
     it('should publish a message', function(done) {
-      conn.getTopic('topic1', function(err, topic) {
-        topic.publish('message from me', done);
-      });
+      pubsub.topic(topicNames[0])
+        .publish('message from me', done);
     });
 
     it('should be deleted', function(done) {
-      conn.getTopic('topic3', function(err, topic) {
-        topic.del(done);
-      });
+      pubsub.topic(topicNames[0])
+        .delete(done);
     });
   });
 
   describe('Subscription', function() {
+    var TOPIC_NAME = 'test-topic';
+    var subscriptions = [
+      {
+        name: 'sub1',
+        options: { ackDeadlineSeconds: 30 }
+      },
+      {
+        name: 'sub2',
+        options: { ackDeadlineSeconds: 60 }
+      }
+    ];
+    var topic;
+
+    function deleteAllTopics(callback) {
+      pubsub.getTopics(function(err, topics) {
+        if (err) {
+          callback(err);
+          return;
+        }
+        async.parallel(topics.map(function(topic) {
+          return topic.delete.bind(topic);
+        }), callback);
+      });
+    }
+
+    function deleteAllSubscriptions(callback) {
+      pubsub.getSubscriptions(function(err, subs) {
+        if (err) {
+          callback(err);
+          return;
+        }
+        async.parallel(subs.map(function(sub) {
+          return sub.delete.bind(sub);
+        }), callback);
+      });
+    }
+
     before(function(done) {
-      var createFn = function(item, callback) {
-        conn.createSubscription({
-          name: item.name,
-          topic: 'topic1',
-          ackDeadlineSeconds: item.ackDeadlineSeconds
-        }, callback);
-      };
-      conn.listSubscriptions(function(err, subs) {
+      async.parallel([deleteAllTopics, deleteAllSubscriptions], function(err) {
         assert.ifError(err);
-        var fns = subs.map(function(sub) {
-          return function(cb) {
-            sub.del(cb);
-          };
-        });
-        async.series(fns, function(err) {
+        // Create a new test topic.
+        pubsub.createTopic(TOPIC_NAME, function(err, newTopic) {
           assert.ifError(err);
-          async.map(subscriptions, createFn, done);
+          topic = newTopic;
+          // Create subscriptions.
+          async.parallel(subscriptions.map(function(sub) {
+            return topic.subscribe.bind(topic, sub.name, sub.options);
+          }), done);
         });
       });
     });
 
-    it('should be listed', function(done) {
-      conn.listSubscriptions(function(err, subs) {
-        assert.strictEqual(subs.length, 2);
-        done(err);
-      });
+    after(function(done) {
+      topic.delete(done);
     });
 
-    it('should be gettable', function(done) {
-      conn.getSubscription('sub1', function(err, sub) {
+    it('should list all subscriptions registered to the topic', function(done) {
+      topic.getSubscriptions(function(err, subs) {
         assert.ifError(err);
-        assert.strictEqual(sub.name, '/subscriptions/' + env.projectId +
-          '/sub1');
+        assert(subs[0] instanceof Subscription);
+        assert.equal(subs.length, subscriptions.length);
         done();
       });
     });
 
-    it('should error while getting a non-existent subscription', function(done){
-      conn.getSubscription('sub-nothing-is-here', function(err) {
-        assert.strictEqual(err.code, 404);
+    it('should allow creation of a topic', function(done) {
+      topic.subscribe('new-subscription', function(err, sub) {
+        assert.ifError(err);
+        assert(sub instanceof Subscription);
         done();
       });
     });
 
-    it('should be created', function(done) {
-      conn.createSubscription({
-        topic: 'topic1',
-        name: 'new-sub'
-      }, done);
+    it('should error when using a non-existent subscription', function(done) {
+      var subscription = topic.subscription('non-existent-subscription');
+      subscription.pull(function(err) {
+        assert.equal(err.code, 404);
+        done();
+      });
     });
 
     it('should be able to pull and ack', function(done) {
-      conn.getTopic('topic1', function(err, topic) {
-        assert.ifError(err);
-        topic.publish('hello', function(err) {
-          assert.ifError(err);
-        });
-      });
-      conn.getSubscription('sub1', function(err, sub) {
+      var subscription = topic.subscription(subscriptions[0].name);
+      subscription.pull({ returnImmediately: true }, function(err, msg) {
         assert.ifError(err);
-        sub.on('message', function(msg) {
-          sub.ack(msg.ackId, done);
-        });
-        sub.pull({}, function() {});
+        subscription.ack(msg.id, done);
       });
+      topic.publish('hello', assert.ifError);
+      topic.publish('hello', assert.ifError);
+      topic.publish('hello', assert.ifError);
+      topic.publish('hello', assert.ifError);
+      topic.publish('hello', assert.ifError);
+      topic.publish('hello', assert.ifError);
     });
   });
 });
diff --git a/scripts/docs.sh b/scripts/docs.sh
new file mode 100755
index 000000000000..0aa64515cf40
--- /dev/null
+++ b/scripts/docs.sh
@@ -0,0 +1,27 @@
+#!/bin/bash
+
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+./node_modules/.bin/dox < lib/index.js > docs/json/master/index.json &
+
+./node_modules/.bin/dox < lib/datastore/dataset.js > docs/json/master/datastore/dataset.json &
+./node_modules/.bin/dox < lib/datastore/index.js > docs/json/master/datastore/index.json &
+./node_modules/.bin/dox < lib/datastore/query.js > docs/json/master/datastore/query.json &
+
+./node_modules/.bin/dox < lib/pubsub/index.js > docs/json/master/pubsub/index.json &
+./node_modules/.bin/dox < lib/pubsub/subscription.js > docs/json/master/pubsub/subscription.json &
+./node_modules/.bin/dox < lib/pubsub/topic.js > docs/json/master/pubsub/topic.json &
+
+./node_modules/.bin/dox < lib/storage/index.js > docs/json/master/storage/index.json &
diff --git a/test/pubsub/index.js b/test/pubsub/index.js
index d249ed97379d..da93518d77bd 100644
--- a/test/pubsub/index.js
+++ b/test/pubsub/index.js
@@ -14,81 +14,174 @@
  * limitations under the License.
  */
 
-/*global describe, it */
+/*global describe, it, beforeEach */
 
 'use strict';
 
 var assert = require('assert');
-var pubsub = require('../../lib/pubsub');
-
-describe('Subscription', function() {
-  it('should ack messages if autoAck is set', function(done) {
-    var sub = new pubsub.Subscription({}, 'sub1');
-    sub.autoAck = true;
-    sub.conn.makeReq = function(method, path, qs, body, callback) {
-      if (path === 'subscriptions/pull') {
-        callback(null, { ackId: 'ackd-id' });
-        return;
-      }
-      if (path === 'subscriptions/acknowledge') {
-        done();
-      }
+var PubSub = require('../../lib/pubsub/index.js');
+var Subscription = require('../../lib/pubsub/subscription.js');
+var Topic = require('../../lib/pubsub/topic.js');
+
+describe('PubSub', function() {
+  var PROJECT_ID = 'test-project';
+  var pubsub;
+
+  beforeEach(function() {
+    pubsub = new PubSub({ projectId: PROJECT_ID });
+    pubsub.makeReq_ = function(method, path, q, body, callback) {
+      callback();
     };
-    sub.pull({}, function() {});
   });
 
-  it('should be closed', function(done) {
-    var sub = new pubsub.Subscription({}, 'sub1');
-    sub.close();
-    assert.strictEqual(sub.closed, true);
-    done();
+  describe('getTopics', function() {
+    beforeEach(function() {
+      pubsub.makeReq_ = function(method, path, q, body, callback) {
+        callback(null, { topic: [{ name: 'fake-topic' }] });
+      };
+    });
+
+    it('should accept a query and a callback', function(done) {
+      pubsub.getTopics({}, done);
+    });
+
+    it('should accept just a callback', function(done) {
+      pubsub.getTopics(done);
+    });
+
+    it('should build a project-wide query', function() {
+      pubsub.makeReq_ = function(method, path, q) {
+        var query =
+            'cloud.googleapis.com/project in (/projects/' + PROJECT_ID + ')';
+        assert.equal(method, 'GET');
+        assert.equal(path, 'topics');
+        assert.equal(q.query, query);
+      };
+      pubsub.getTopics(function() {});
+    });
+
+    it('should return Topic instances', function() {
+      pubsub.getTopics(function(err, topics) {
+        assert.ifError(err);
+        assert(topics[0] instanceof Topic);
+      });
+    });
+
+    it('should return a query if more results exist', function() {
+      var token = 'next-page-token';
+      pubsub.makeReq_ = function(method, path, q, body, callback) {
+        callback(null, { nextPageToken: token });
+      };
+      var query = { maxResults: 1 };
+      pubsub.getTopics(query, function(err, topics, nextQuery) {
+        assert.ifError(err);
+        assert.strictEqual(query.maxResults, nextQuery.maxResults);
+        assert.equal(query.pageToken, token);
+      });
+    });
+
+    it('should pass error if api returns an error', function() {
+      var error = new Error('Error');
+      pubsub.makeReq_ = function(method, path, q, body, callback) {
+        callback(error);
+      };
+      pubsub.getTopics(function(err) {
+        assert.equal(err, error);
+      });
+    });
   });
 
-  it('should pull messages', function(done) {
-    var conn = new pubsub.Connection({
-      projectId: 'test-project'
-    });
-    conn.makeReq = function(method, path, qs, body, callback) {
-      if (path === 'subscriptions//subscriptions/test-project/sub1') {
-        callback(null, {});
-        return;
-      }
-      if (path === 'subscriptions/pull') {
-        callback(null, { ackId: 123 });
-        return;
-      }
-    };
-    var sub = conn.subscribe('sub1', { autoAck: false });
-    sub.once('message', function() {
-      sub.close();
-      done();
+  describe('createTopic', function() {
+    it('should create a topic', function() {
+      var topicName = 'new-topic-name';
+      pubsub.makeReq_ = function(method, path, q, body) {
+        assert.equal(method, 'POST');
+        assert.equal(path, 'topics');
+        assert.equal(body.name, '/topics/' + PROJECT_ID + '/' + topicName);
+      };
+      pubsub.createTopic(topicName, function() {});
+    });
+
+    it('should return a Topic object', function() {
+      pubsub.createTopic('new-topic', function(err, topic) {
+        assert.ifError(err);
+        assert(topic instanceof Topic);
+      });
     });
   });
 
-  it('should pull and ack messages', function(done) {
-    var conn = new pubsub.Connection({
-      projectId: 'test-project'
-    });
-    conn.makeReq = function(method, path, qs, body, callback) {
-      if (path === 'subscriptions//subscriptions/test-project/sub1') {
-        callback(null, {});
-        return;
-      }
-      if (path === 'subscriptions/pull') {
-        setImmediate(function() {
-          callback(null, { ackId: 123 });
-        });
-        return;
-      }
-      if (path === 'subscriptions/acknowledge') {
-        callback(null, true);
-        return;
-      }
-    };
-    var sub = conn.subscribe('sub1', { autoAck: true });
-    sub.once('message', function() {
-      sub.close();
-      done();
+  describe('topic', function() {
+    it('should throw if a name is not provided', function() {
+      assert.throws(function() {
+        pubsub.topic();
+      }, /name must be specified/);
     });
+
+    it('should return a Topic object', function() {
+      assert(pubsub.topic('new-topic') instanceof Topic);
+    });
+  });
+
+  describe('getSubscriptions', function() {
+    beforeEach(function() {
+      pubsub.makeReq_ = function(method, path, q, body, callback) {
+        callback(null, { subscription: [{ name: 'fake-subscription' }] });
+      };
+    });
+
+    it('should accept a query and a callback', function(done) {
+      pubsub.getSubscriptions({}, done);
+    });
+
+    it('should accept just a callback', function(done) {
+      pubsub.getSubscriptions(done);
+    });
+
+    it('should build a project-wide query', function() {
+      pubsub.makeReq_ = function(method, path, q) {
+        var query =
+            'cloud.googleapis.com/project in (/projects/' + PROJECT_ID + ')';
+        assert.equal(method, 'GET');
+        assert.equal(path, 'subscriptions');
+        assert.equal(q.query, query);
+      };
+      pubsub.getSubscriptions(function() {});
+    });
+
+    it('should return Subscription instances', function() {
+      pubsub.getSubscriptions(function(err, subscriptions) {
+        assert.ifError(err);
+        assert(subscriptions[0] instanceof Subscription);
+      });
+    });
+
+    it('should return a query if more results exist', function() {
+      var token = 'next-page-token';
+      pubsub.makeReq_ = function(method, path, q, body, callback) {
+        callback(null, { nextPageToken: token });
+      };
+      var query = { maxResults: 1 };
+      pubsub.getSubscriptions(query, function(err, subscriptions, nextQuery) {
+        assert.ifError(err);
+        assert.strictEqual(query.maxResults, nextQuery.maxResults);
+        assert.equal(query.pageToken, token);
+      });
+    });
+
+    it('should pass error if api returns an error', function() {
+      var error = new Error('Error');
+      pubsub.makeReq_ = function(method, path, q, body, callback) {
+        callback(error);
+      };
+      pubsub.getSubscriptions(function(err) {
+        assert.equal(err, error);
+      });
+    });
+  });
+
+  it('should pass network requests to the connection object', function(done) {
+    var pubsub = new PubSub();
+    pubsub.connection.req = done.bind(null, null);
+    pubsub.makeReq_();
   });
 });
diff --git a/test/pubsub/subscription.js b/test/pubsub/subscription.js
new file mode 100644
index 000000000000..2d1ed3206e7e
--- /dev/null
+++ b/test/pubsub/subscription.js
@@ -0,0 +1,430 @@
+/**
+ * Copyright 2014 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*global describe, it, beforeEach, afterEach */
+
+'use strict';
+
+var assert = require('assert');
+var util = require('../../lib/common/util.js');
+var Subscription = require('../../lib/pubsub/subscription.js');
+
+describe('Subscription', function() {
+  var PROJECT_ID = 'test-project';
+  var SUB_NAME = 'test-subscription';
+  var SUB_FULL_NAME = '/subscriptions/' + PROJECT_ID + '/' + SUB_NAME;
+  var pubsubMock = {
+    projectId: PROJECT_ID,
+    makeReq_: util.noop
+  };
+  var message = 'howdy';
+  var messageBuffer = new Buffer(message).toString('base64');
+  var messageObj = {
+    ackId: 3,
+    pubsubEvent: {
+      message: {
+        data: messageBuffer
+      }
+    }
+  };
+  var expectedMessage = { id: 3, data: message };
+  var subscription;
+
+  beforeEach(function() {
+    subscription = new Subscription(pubsubMock, { name: SUB_NAME });
+  });
+
+  describe('initialization', function() {
+    it('should format name', function(done) {
+      var formatName_ = Subscription.formatName_;
+      Subscription.formatName_ = function() {
+        Subscription.formatName_ = formatName_;
+        done();
+      };
+      new Subscription(pubsubMock, { name: SUB_NAME });
+    });
+
+    it('should honor configuration settings', function() {
+      var CONFIG = {
+        name: SUB_NAME,
+        autoAck: true,
+        interval: 100
+      };
+      var sub = new Subscription(pubsubMock, CONFIG);
+      assert.strictEqual(sub.autoAck, CONFIG.autoAck);
+      assert.strictEqual(sub.interval, CONFIG.interval);
+    });
+
+    it('should not be closed', function() {
+      assert.strictEqual(subscription.closed, false);
+    });
+
+    it('should default autoAck to false if not specified', function() {
+      var sub = new Subscription(pubsubMock, { name: SUB_NAME });
+      assert.strictEqual(sub.autoAck, false);
+    });
+
+    it('should set default interval if one is not specified', function() {
+      var sub = new Subscription(pubsubMock, { name: SUB_NAME });
+      assert.equal(sub.interval, 10);
+    });
+  });
+
+  describe('formatName_', function() {
+    it('should format name', function() {
+      var formattedName = Subscription.formatName_(PROJECT_ID, SUB_NAME);
+      assert.equal(formattedName, SUB_FULL_NAME);
+    });
+
+    it('should format name when given a complete name', function() {
+      var formattedName = Subscription.formatName_(PROJECT_ID, SUB_FULL_NAME);
+      assert.equal(formattedName, SUB_FULL_NAME);
+    });
+  });
+
+  describe('listenForEvents_', function() {
+    afterEach(function() {
+      subscription.removeAllListeners();
+    });
+
+    it('should start pulling once a message listener is bound', function(done) {
+      subscription.startPulling_ = function() {
+        done();
+      };
+      subscription.on('message', util.noop);
+    });
+
+    it('should close when no more message listeners are bound', function() {
+      subscription.startPulling_ = util.noop;
+      subscription.on('message', util.noop);
+      subscription.on('message', util.noop);
+      // 2 listeners: sub should be open.
+      assert.strictEqual(subscription.closed, false);
+      subscription.removeListener('message', util.noop);
+      // 1 listener: sub should be open.
+      assert.strictEqual(subscription.closed, false);
+      subscription.removeListener('message', util.noop);
+      // 0 listeners: sub should be closed.
+      assert.strictEqual(subscription.closed, true);
+    });
+  });
+
+  describe('ack', function() {
+    it('should throw if no IDs are provided', function() {
+      assert.throws(function() {
+        subscription.ack();
+      }, /At least one ID/);
+      assert.throws(function() {
+        subscription.ack([]);
+      }, /At least one ID/);
+    });
+
+    it('should accept a single id', function() {
+      assert.doesNotThrow(function() {
+        subscription.ack(1, util.noop);
+      });
+    });
+
+    it('should accept an array of ids', function() {
+      assert.doesNotThrow(function() {
+        subscription.ack([1], util.noop);
+      });
+    });
+
+    it('should make an array out of ids', function(done) {
+      var ID = 1;
+      subscription.makeReq_ = function(method, path, qs, body) {
+        assert.equal(body.subscription, SUB_FULL_NAME);
+        assert.deepEqual(body.ackId, [ID]);
+        done();
+      };
+      subscription.ack(ID, assert.ifError);
+    });
+
+    it('should make correct api request', function(done) {
+      var IDS = [1, 2, 3];
+      subscription.makeReq_ = function(method, path, qs, body) {
+        assert.equal(body.subscription, SUB_FULL_NAME);
+        assert.deepEqual(body.ackId, IDS);
+        done();
+      };
+      subscription.ack(IDS, assert.ifError);
+    });
+
+    it('should pass callback to request', function(done) {
+      subscription.makeReq_ = function(method, path, qs, body, callback) {
+        callback();
+      };
+      subscription.ack(1, done);
+    });
+  });
+
+  describe('pull', function() {
+    beforeEach(function() {
+      subscription.ack = util.noop;
+      subscription.makeReq_ = function(method, path, qs, body, callback) {
+        callback(null, messageObj);
+      };
+    });
+
+    it('should make correct api request', function(done) {
+      subscription.makeReq_ = function(method, path, qs, body) {
+        assert.equal(method, 'POST');
+        assert.equal(path, 'subscriptions/pull');
+        assert.equal(body.subscription, SUB_FULL_NAME);
+        assert.strictEqual(body.returnImmediately, false);
+        done();
+      };
+      subscription.pull({}, assert.ifError);
+    });
+
+    it('should not require configuration options', function(done) {
+      subscription.pull(done);
+    });
+
+    it('should default returnImmediately to false', function(done) {
+      subscription.makeReq_ = function(method, path, qs, body) {
+        assert.strictEqual(body.returnImmediately, false);
+        done();
+      };
+      subscription.pull({}, assert.ifError);
+    });
+
+    it('should honor options', function(done) {
+      subscription.makeReq_ = function(method, path, qs, body) {
+        assert.strictEqual(body.returnImmediately, true);
+        done();
+      };
+      subscription.pull({ returnImmediately: true }, assert.ifError);
+    });
+
+    it('should pass error to callback', function(done) {
+      var error = new Error('Error.');
+      subscription.makeReq_ = function(method, path, qs, body, callback) {
+        callback(error);
+      };
+      subscription.pull(function(err) {
+        assert.equal(err, error);
+        done();
+      });
+    });
+
+    describe('autoAck false', function() {
+      beforeEach(function() {
+        subscription.autoAck = false;
+      });
+
+      it('should not ack', function() {
+        subscription.ack = function() {
+          throw new Error('Should not have acked.');
+        };
+        subscription.pull({}, assert.ifError);
+      });
+
+      it('should execute callback with message', function(done) {
+        subscription.pull({}, function(err, msg) {
+          assert.deepEqual(msg, expectedMessage);
+          done();
+        });
+      });
+    });
+
+    describe('autoAck true', function() {
+      beforeEach(function() {
+        subscription.autoAck = true;
+        subscription.ack = function(id, callback) {
+          callback();
+        };
+      });
+
+      it('should ack', function(done) {
+        subscription.ack = function() {
+          done();
+        };
+        subscription.pull({}, assert.ifError);
+      });
+
+      it('should pass id to ack', function(done) {
+        subscription.ack = function(id) {
+          assert.equal(id, expectedMessage.id);
+          done();
+        };
+        subscription.pull({}, assert.ifError);
+      });
+
+      it('should pass callback to ack', function(done) {
+        subscription.pull({}, done);
+      });
+
+      it('should invoke callback with error from ack', function(done) {
+        var error = new Error('Error.');
+        subscription.ack = function(id, callback) {
+          callback(error);
+        };
+        subscription.pull({}, function(err) {
+          assert.equal(err, error);
+          done();
+        });
+      });
+
+      it('should execute callback', function(done) {
+        subscription.pull({}, done);
+      });
+    });
+  });
+
+  describe('startPulling_', function() {
+    beforeEach(function() {
+      subscription.pull = util.noop;
+    });
+
+    it('should pull at specified interval', function(done) {
+      var INTERVAL = 5;
+      subscription.pull = function(options, callback) {
+        // After pull is called once, overwrite with `done`.
+        // This is to override the function passed to `setTimeout`, so we are
+        // sure it's the same pull function when we execute it.
+        subscription.pull = function() {
+          done();
+        };
+        callback();
+      };
+      var setTimeout = global.setTimeout;
+      global.setTimeout = function(fn, interval) {
+        global.setTimeout = setTimeout;
+        assert.equal(interval, INTERVAL);
+        // This should execute the `done` function from when we overrided it
+        // above.
+        fn();
+      };
+      subscription.interval = INTERVAL;
+      subscription.startPulling_();
+    });
+
+    it('should stop pulling if subscription is closed', function() {
+      var pulledCount = 0;
+      subscription.pull = function() {
+        if (++pulledCount === 3) {
+          subscription.pull = function() {
+            throw Error('Should have stopped pulling.');
+          };
+          subscription.close();
+        }
+      };
+      subscription.startPulling_();
+    });
+
+    it('should set returnImmediately to false when pulling', function(done) {
+      subscription.pull = function(options) {
+        assert.strictEqual(options.returnImmediately, false);
+        done();
+      };
+      subscription.startPulling_();
+    });
+
+    it('should emit an error event if one is encountered', function(done) {
+      var error = new Error('Error.');
+      subscription.pull = function(options, callback) {
+        subscription.pull = function() {};
+        setImmediate(function() {
+          callback(error);
+        });
+      };
+      subscription
+        .once('error', function(err) {
+          assert.equal(err, error);
+          done();
+        })
+        .startPulling_();
+    });
+
+    it('should emit a message event', function(done) {
+      subscription.pull = function(options, callback) {
+        callback(null, { hi: 'there' });
+      };
+      subscription
+        .once('message', function(msg) {
+          assert.deepEqual(msg, { hi: 'there' });
+          done();
+        });
+    });
+  });
+
+  describe('delete', function() {
+    it('should delete a subscription', function(done) {
+      subscription.makeReq_ = function(method, path) {
+        assert.equal(method, 'DELETE');
+        assert.equal(path, 'subscriptions/' + subscription.name);
+        done();
+      };
+      subscription.delete();
+    });
+
+    it('should close a subscription once deleted', function() {
+      subscription.makeReq_ = function(method, path, qs, body, callback) {
+        callback();
+      };
+      subscription.closed = false;
+      subscription.delete();
+      assert.strictEqual(subscription.closed, true);
+    });
+
+    it('should remove all listeners', function(done) {
+      subscription.makeReq_ = function(method, path, qs, body, callback) {
+        callback();
+      };
+      subscription.removeAllListeners = function() {
+        done();
+      };
+      subscription.delete();
+    });
+
+    it('should execute callback when deleted', function(done) {
+      subscription.makeReq_ = function(method, path, qs, body, callback) {
+        callback();
+      };
+      subscription.delete(done);
+    });
+
+    it('should execute callback with an api error', function(done) {
+      var error = new Error('Error.');
+      subscription.makeReq_ = function(method, path, qs, body, callback) {
+        callback(error);
+      };
+      subscription.delete(function(err) {
+        assert.equal(err, error);
+        done();
+      });
+    });
+  });
+
+  describe('formatMessage_', function() {
+    it('should decode stringified JSON to object', function() {
+      var obj = { hi: 'there' };
+      var stringified = new Buffer(JSON.stringify(obj)).toString('base64');
+      var msg = Subscription.formatMessage_({
+        ackId: 3,
+        pubsubEvent: { message: { data: stringified } }
+      });
+      assert.deepEqual(msg, { id: 3, data: obj });
+    });
+
+    it('should decode buffer to string', function() {
+      var msg = Subscription.formatMessage_(messageObj);
+      assert.deepEqual(msg, expectedMessage);
+    });
+  });
+});
diff --git a/test/pubsub/topic.js b/test/pubsub/topic.js
new file mode 100644
index 000000000000..800076b0a528
--- /dev/null
+++ b/test/pubsub/topic.js
@@ -0,0 +1,341 @@
+/**
+ * Copyright 2014 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*global describe, it, beforeEach, afterEach */
+
+'use strict';
+
+var assert = require('assert');
+var util = require('../../lib/common/util.js');
+
+var SubscriptionCached = require('../../lib/pubsub/subscription.js');
+var formatName_Cached = SubscriptionCached.formatName_;
+var SubscriptionOverride;
+var formatName_Override;
+
+function Subscription(a, b) {
+  var OverrideFn = SubscriptionOverride || SubscriptionCached;
+  return new OverrideFn(a, b);
+}
+
+Subscription.formatName_ = function() {
+  var args = [].slice.apply(arguments);
+  return (formatName_Override || formatName_Cached).apply(null, args);
+};
+
+var Topic = require('sandboxed-module')
+    .require('../../lib/pubsub/topic.js', {
+      requires: {
+        './subscription.js': Subscription
+      }
+    });
+
+describe('Topic', function() {
+  var PROJECT_ID = 'test-project';
+  var TOPIC_NAME = 'test-topic';
+  var pubsubMock = {
+    projectId: PROJECT_ID,
+    makeReq_: util.noop
+  };
+  var topic;
+
+  beforeEach(function() {
+    topic = new Topic(pubsubMock, { name: TOPIC_NAME });
+  });
+
+  afterEach(function() {
+    SubscriptionOverride = null;
+    formatName_Override = null;
+  });
+
+  describe('initialization', function() {
+    it('should format name', function(done) {
+      var formatName_ = Topic.formatName_;
+      Topic.formatName_ = function() {
+        Topic.formatName_ = formatName_;
+        done();
+      };
+      new Topic(pubsubMock, { name: TOPIC_NAME });
+    });
+
+    it('should assign projectId to `this`', function() {
+      assert.equal(topic.projectId, PROJECT_ID);
+    });
+
+    it('should assign pubsub object to `this`', function() {
+      assert.deepEqual(topic.pubsub, pubsubMock);
+    });
+  });
+
+  describe('formatName_', function() {
+    var fullName = '/topics/' + PROJECT_ID + '/' + TOPIC_NAME;
+
+    it('should format name', function() {
+      var formattedName = Topic.formatName_(PROJECT_ID, TOPIC_NAME);
+      assert.equal(formattedName, fullName);
+    });
+
+    it('should format name when given a complete name', function() {
+      var formattedName = Topic.formatName_(PROJECT_ID, fullName);
+      assert.equal(formattedName, fullName);
+    });
+  });
+
+  describe('publishing', function() {
+    var message = 'howdy';
+    var messageBuffer = new Buffer(message);
+    var messageRaw = { data: messageBuffer.toString('base64') };
+    var messageObj = { test: 'object' };
+    var messageObjDecoded =
+            new Buffer(JSON.stringify(messageObj)).toString('base64');
+
+    describe('publish', function() {
+      it('should throw if no message is provided', function() {
+        assert.throws(function() {
+          topic.publish();
+        }, /empty message/);
+      });
+
+      it('should convert string to raw message', function(done) {
+        topic.publishRaw = function(msg) {
+          assert.deepEqual(msg, messageRaw);
+          done();
+        };
+        topic.publish(message, assert.ifError);
+      });
+
+      it('should convert buffer to raw message', function(done) {
+        topic.publishRaw = function(msg) {
+          assert.deepEqual(msg, messageRaw);
+          done();
+        };
+        topic.publish(messageBuffer, assert.ifError);
+      });
+
+      it('should stringify non-strings & non-buffers', function(done) {
+        topic.publishRaw = function(msg) {
+          assert.deepEqual(msg.data, messageObjDecoded);
+          done();
+        };
+        topic.publish(messageObj, assert.ifError);
+      });
+
+      it('should pass callback', function(done) {
+        topic.publishRaw = function(msg, callback) {
+          callback();
+        };
+        topic.publish(message, done);
+      });
+    });
+
+    describe('publishRaw', function() {
+      it('should throw if no message is provided', function() {
+        assert.throws(function() {
+          topic.publishRaw();
+        }, /empty message/);
+      });
+
+      it('should stringify non-strings & non-buffers', function(done) {
+        topic.makeReq_ = function(method, path, qs, body) {
+          assert.deepEqual(body.data, messageObjDecoded);
+          done();
+        };
+        topic.publishRaw({ data: messageObj }, assert.ifError);
+      });
+
+      it('should post raw messages to the api', function(done) {
+        topic.makeReq_ = function(method, path, qs, body) {
+          assert.equal(method, 'POST');
+          assert.equal(path, 'topics/publish');
+          assert.deepEqual(body.message, messageRaw.message);
+          done();
+        };
+        topic.publishRaw(messageRaw, assert.ifError);
+      });
+
+      it('should attach topic name to the request', function(done) {
+        topic.makeReq_ = function(method, path, qs, body) {
+          assert.equal(body.topic, topic.name);
+          done();
+        };
+        topic.publishRaw(messageRaw, assert.ifError);
+      });
+    });
+  });
+
+  describe('delete', function() {
+    it('should delete a topic', function(done) {
+      topic.makeReq_ = function(method, path) {
+        assert.equal(method, 'DELETE');
+        assert.equal(path, 'topics/' + topic.name);
+        done();
+      };
+      topic.delete();
+    });
+  });
+
+  describe('subscriptions', function() {
+    var SUB_NAME = 'new-sub-name';
+    var SUB_FULL_NAME = '/subscriptions/' + PROJECT_ID + '/' + SUB_NAME;
+    var CONFIG = { autoAck: true, interval: 90 };
+
+    describe('getSubscriptions', function() {
+      it('should call parent getSubscriptions', function(done) {
+        topic.pubsub.getSubscriptions = function() {
+          done();
+        };
+        topic.getSubscriptions(assert.ifError);
+      });
+
+      it('should pass query', function(done) {
+        var query = { pageToken: 1, maxResults: 3 };
+        topic.pubsub.getSubscriptions = function(q) {
+          assert.strictEqual(q.pageToken, query.pageToken);
+          assert.strictEqual(q.maxResults, query.maxResults);
+          done();
+        };
+        topic.getSubscriptions(query, assert.ifError);
+      });
+
+      it('should pass callback', function(done) {
+        topic.pubsub.getSubscriptions = function(q, callback) {
+          callback();
+        };
+        topic.getSubscriptions({}, done);
+      });
+
+      it('should attach scoped topic query to query object', function(done) {
+        topic.pubsub.getSubscriptions = function(q) {
+          assert.equal(
+              q.query, 'pubsub.googleapis.com/topic in (' + topic.name + ')');
+          done();
+        };
+        topic.getSubscriptions({}, assert.ifError);
+      });
+    });
+
+    describe('subscribe', function() {
+      it('should throw if no name is provided', function() {
+        assert.throws(function() {
+          topic.subscribe();
+        }, /name.*required/);
+      });
+
+      it('should not require configuration options', function(done) {
+        topic.makeReq_ = function(method, path, qs, body, callback) {
+          callback();
+        };
+        topic.subscribe(SUB_NAME, done);
+      });
+
+      it('should format provided name', function(done) {
+        formatName_Override = function() {
+          done();
+        };
+        topic.subscribe(SUB_NAME, assert.ifError);
+      });
+
+      it('should send correct request', function(done) {
+        topic.makeReq_ = function(method, path, qs, body) {
+          assert.equal(method, 'POST');
+          assert.equal(path, 'subscriptions');
+          assert.equal(body.topic, topic.name);
+          assert.equal(body.name, SUB_FULL_NAME);
+          done();
+        };
+        topic.subscribe(SUB_NAME, assert.ifError);
+      });
+
+      it('should return an api error to the callback', function(done) {
+        var error = new Error('Error.');
+        topic.makeReq_ = function(method, path, qs, body, callback) {
+          callback(error);
+        };
+        topic.subscribe(SUB_NAME, function(err) {
+          assert.equal(err, error);
+          done();
+        });
+      });
+
+      it('should create a new subscription', function(done) {
+        topic.subscription = function(name) {
+          assert.equal(name, SUB_NAME);
+          done();
+        };
+        topic.makeReq_ = function(method, path, qs, body, callback) {
+          callback();
+        };
+        topic.subscribe(SUB_NAME, assert.ifError);
+      });
+
+      it('should honor settings on the api request', function(done) {
+        var SEC = 90;
+        topic.makeReq_ = function(method, path, qs, body) {
+          assert.strictEqual(body.ackDeadlineSeconds, SEC);
+          done();
+        };
+        topic.subscribe(SUB_NAME, { ackDeadlineSeconds: SEC }, assert.ifError);
+      });
+
+      it('should honor settings on the subscription object', function(done) {
+        topic.subscription = function(name, options) {
+          assert.deepEqual(options, CONFIG);
+          done();
+        };
+        topic.makeReq_ = function(method, path, qs, body, callback) {
+          callback();
+        };
+        topic.subscribe(SUB_NAME, CONFIG, assert.ifError);
+      });
+    });
+
+    describe('subscription', function() {
+      it('should throw if no name is provided', function() {
+        assert.throws(function() {
+          topic.subscription();
+        }, /name.*required/);
+      });
+
+      it('should return a Subscription object', function() {
+        SubscriptionOverride = function() {};
+        var subscription = topic.subscription(SUB_NAME, {});
+        assert(subscription instanceof SubscriptionOverride);
+      });
+
+      it('should honor settings', function(done) {
+        SubscriptionOverride = function(pubsub, options) {
+          assert.deepEqual(options, CONFIG);
+          done();
+        };
+        topic.subscription(SUB_NAME, CONFIG);
+      });
+
+      it('should pass specified name to the Subscription', function(done) {
+        SubscriptionOverride = function(pubsub, options) {
+          assert.equal(options.name, SUB_NAME);
+          done();
+        };
+        topic.subscription(SUB_NAME, {});
+      });
+
+      it('should not require options', function() {
+        assert.doesNotThrow(function() {
+          topic.subscription(SUB_NAME);
+        });
+      });
+    });
+  });
+});