googleapis - npm Package Compare versions

Comparing version 0.2.0 to 0.2.1-alpha

lib/client.js

 /**
- * @author [e-mail] (Burcu Dogan)
+ * Copyright 2012 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.
  */
 
-var Request = require('./request.js')
-  , BatchRequest = require('./batchrequest.js');
+var Request = require('./requests.js').Request;
+var BatchRequest = require('./requests.js').BatchRequest;
 
@@ -12,4 +24,3 @@ /**
  *
- * @param {object} apiMeta
- * @return {Client}
+ * @param {object} apiMeta Schema returned by Discovery API.
  */
@@ -21,5 +32,6 @@ function Client(apiMeta) {
   this.registerHelpers_();
-};
+}
 
 /**
+ * @private
  * Registers request builders for existing API methods.
@@ -35,20 +47,25 @@ */
 /**
- * TODO: add documentation, move to utils
+ * @private
+ * TODO(burcud): move to utils
  *
- * @param {?object} root
- * @param {string} key
- * @param {?object} obj
+ * @param {?object} root Object to be extended.
+ * @param {string} key Full key.
+ * @param {?object} obj Object to extend root object with.
+ * @return {object} Extended object.
  */
 Client.prototype.extend_ = function(root, key, obj) {
 
-  if(!root) root = {};
-  var keys = key.split('.');
+  if (!root) root = {};
+  var namespaceKeys = key.split('.');
 
   var chain = root;
-  for (var i in keys) {
-    var chainKey = keys[i];
+  for (var i = 0; i < namespaceKeys.length; i++) {
+    var chainKey = namespaceKeys[i];
 
     // if this is the last key, put obj in it.
-    if (i == keys.length - 1) chain[chainKey] = obj;
-    else if (!chain[chainKey]) chain[chainKey] = {};
+    if (i == namespaceKeys.length - 1) {
+      chain[chainKey] = obj;
+    } else if (!chain[chainKey]) {
+      chain[chainKey] = {};
+    }
 
@@ -63,6 +80,7 @@ // move to the next key
 /**
+ * @private
  * Generate a request builder helper.
  *
- * @param {object} methodMeta
- * @return {Function} method
+ * @param {object} methodMeta Method's schema returned by Discovery API.
+ * @return {Function} Function generated by methodMeta.
  */
@@ -75,4 +93,4 @@ Client.prototype.generateHelper_ = function(methodMeta) {
   // to the resource on given method
-  return function(params) {
-    return that.newRequest(methodMeta.id, params);
+  return function(params, resource) {
+    return that.newRequest(methodMeta.id, params, resource);
   };
@@ -84,7 +102,10 @@ };
  *
- * @param {string} methodName
- * @param {object=} opt_params
+ * @param {string} methodName Full name of the method.
+ * @param {?object} params Parameters.
+ * @param {object=} opt_resource Optional resource.
+ *
+ * @return {Request} New Request object constructed with given args.
  */
-Client.prototype.newRequest = function(methodName, opt_params) {
-  return new Request(this.apiMeta, methodName, opt_params);
+Client.prototype.newRequest = function(methodName, params, opt_resource) {
+  return new Request(this.apiMeta, methodName, params, opt_resource);
 };
@@ -95,3 +116,3 @@
  *
- * @return {Batch}
+ * @return {BatchRequest} New BatchRequest object.
  */
@@ -105,8 +126,14 @@ Client.prototype.newBatchRequest = function() {
  *
- * @param {string|null} apiKey
+ * @param {?string} apiKey API Key.
+ *
+ * @return {Client} Returns itself.
  */
-Client.prototype.setApiKey = function(apiKey) {
+Client.prototype.withApiKey = function(apiKey) {
   this.apiMeta.apiKey = apiKey;
-}
+  return this;
+};
 
+/**
+ * Exporting Client.
+ */
 module.exports = Client;

lib/googleapis.js

 /**
- * @author [e-mail] (Burcu Dogan)
+ * Copyright 2012 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.
  */
 
-var Client = require('./client.js')
-  , request = require('request');
+var Client = require('./client.js');
+var DefaultTransporter = require('./transporters.js');
+var qs = require('querystring');
 
@@ -12,30 +25,39 @@ /**
  *
- * @param {string} name
- * @param {string} version
+ * @param {string} name Name of the API.
+ * @param {string} version Version of the API.
+ * @param {object=} opt_config Optional configuration.
  */
-function GoogleApis(name, version) {
+function GoogleApis(name, version, opt_config) {
   this.name = name;
   this.version = version;
-};
+  this.config = opt_config || {};
+  this.transporter = exports.Transporter ||
+      new DefaultTransporter();
+}
 
 /**
  * @const
+ * @private
  * Base path for discovery API.
  * @type {string}
  */
-GoogleApis.BASE_DISCOVERY_URL_ = 'https://www.googleapis.com/discovery/v1/apis/';
+GoogleApis.BASE_DISCOVERY_URL_ =
+  'https://www.googleapis.com/discovery/v1/apis/';
 
 /**
  * @const
+ * @private
  * Discovery type.
  * @type {string}
  */
-GoogleApis.DISCOVERY_TYPE_ = '/rpc';
+// TODO(burcud): Switch to REST.
+GoogleApis.DISCOVERY_TYPE_ = 'rpc';
 
 /**
  * @const
+ * @private
  * Additional discovery parameters.
- * @type {string}
+ * @type {object}
  */
-GoogleApis.DISCOVERY_PARAMS_ = '';
+GoogleApis.DISCOVERY_PARAMS_ = null;
 
@@ -45,16 +67,15 @@ /**
  *
- * @param {Function=} opt_callback
+ * @param {Function=} opt_callback Optional callback function.
  */
-GoogleApis.prototype.load = function (opt_callback) {
+GoogleApis.prototype.load = function(opt_callback) {
   // make the request and generate client
-  request({
-    uri: this.generateDiscoveryUrl_()
-  }, function(err, res, body){
+  var opts = {
+    uri: this.generateDiscoveryUrl(), json: true
+  };
 
+  this.transporter.request(opts, function(err, json, res) {
     var client = null;
-    if (!err && body){
-      // TODO: dont crash if body is not valid json
-      client = new Client(JSON.parse(body));
+    if (!err && json) {
+      client = new Client(json);
     }
-
     opt_callback && opt_callback(err, client);
@@ -67,11 +88,21 @@ });
  *
- * @return {string} discoveryUrl
+ * @return {string} discoveryUrl.
  */
-GoogleApis.prototype.generateDiscoveryUrl_ = function() {
+GoogleApis.prototype.generateDiscoveryUrl = function() {
 
-  var discoveryUrl = GoogleApis.BASE_DISCOVERY_URL_;
-  discoveryUrl += encodeURIComponent(this.name)
-    + '/' + encodeURIComponent(this.version)
-    + GoogleApis.DISCOVERY_TYPE_ + GoogleApis.DISCOVERY_PARAMS_;
+  var baseDiscoveryUrl = this.config.baseDiscoveryUrl ||
+      GoogleApis.BASE_DISCOVERY_URL_;
 
+  var discoveryParams = this.config.discoveryParams ||
+      GoogleApis.DISCOVERY_PARAMS_;
+
+  var discoveryUrl = baseDiscoveryUrl;
+  discoveryUrl += encodeURIComponent(this.name) +
+      '/' + encodeURIComponent(this.version) +
+      '/' + GoogleApis.DISCOVERY_TYPE_;
+
+  if (discoveryParams) {
+    discoveryUrl += '?' + qs.stringify(discoveryParams);
+  }
+
   return discoveryUrl;
@@ -83,8 +114,24 @@ };
  *
- * @param {string} name
- * @param {string} version
- * @param {Function=} opt_callback
+ * @param {string} name Name of the API (e.g. urlshortener).
+ * @param {string} version Version of the API. (e.g. v1).
+ * @param {Function} callback Callback fn.
+ * @param {object=} opt_config Optional configuration.
  */
-exports.load = function(name, version, opt_callback) {
-  new GoogleApis(name, version).load(opt_callback);
+exports.load = function(name, version, callback, opt_config) {
+  new GoogleApis(name, version, opt_config).load(callback);
 };
+
+/**
+ * Exports GoogleApis.
+ */
+exports.GoogleApis = GoogleApis;
+
+/**
+ * Exports Transporter.
+ */
+exports.Transporter = null;
+
+/**
+ * Exports OAuth2Client.
+ */
+exports.OAuth2Client = require('./auth/oauth2client.js');

package.json

 {
   "name": "googleapis",
-  "version": "0.2.0",
-  "author": "Burcu Dogan <[e-mail]>",
-  "description": "Generates node client libs for Google APIs.",
+  "version": "0.2.1-alpha",
+  "author": "Google Inc.",
+  "description": "Google APIs Client Library for Node.js",
   "contributors": [
     {
       "name": "Burcu Dogan",
-      "email": "[e-mail]"
+      "email": "[e-mail]"
+    }, {
+      "name": "Monsur Hossain",
+      "email": "[e-mail]"
     }
@@ -15,3 +18,3 @@ ],
     "type": "git",
-    "url": "https://github.com/burcu/node-googleapis.git"
+    "url": "https://github.com/google/google-api-nodejs-client.git"
   },
@@ -22,8 +25,13 @@ "keywords": [
     "google apis",
-    "client"
+    "client",
+    "client library"
   ],
   "dependencies" : {
-    "request"   :  "*"
+    "request":  "2.14.0"
   },
-  "license": "MIT"
+  "devDependencies" : {
+    "mocha": "1.8.1",
+    "url": "0.7.9"
+  },
+  "license": "Apache 2"
 }

README.md

@@ -1,60 +0,211 @@
-#node-googleapis
+# google-api-nodejs-client [alpha]
 
-``node-googleapis`` allow you to generate client libs for [Google APIs](https://developers.google.com/apis-explorer/).
+`google-api-nodejs-client` is the Google's officially supported
+[node.js](http://nodejs.org/) client
+library for accessing Google APIs, it also supports authorization and
+authentication with OAuth 2.0.
 
+**Note**: This library is currently in *alpha* status, meaning that we can make
+changes in the future that *may not be compatible* with the previous versions.
+
 ## Installation
 
-    npm install googleapis
+The library is distributed on `npm`. In order to add it as a dependency,
+run the following command:
 
-## Usage
+    $ npm install googleapis
 
-    var googleapis = require('googleapis);
+## Guide
 
-    googleapis.load('urlshortener','v1', function(err, client) {
+Dynamically load any Google API and start making requests:
 
-      // set api key
-      client.setApiKey('AIzaSyAdjHPT5Pb7Nu56WJ_nlrMGOAgUAtKjiPM');
+    var googleapis = require('googleapis');
 
-      // batch requests
+    googleapis.load('urlshortener', 'v1', function(err, client) {
+      var params = { shortUrl: 'http://goo.gl/DdUKX' };
+      var request = client.urlshortener.url.get(params);
+      request.execute(function (err, response) {
+        console.log('Long url is', response.longUrl);
+      });
+    });
+
+Supported APIs are listed on
+[Google APIs Explorer](https://developers.google.com/apis-explorer).
+
+### API Clients
+
+Client libraries are generated during runtime by metadata provided by Google
+APIs Discovery Service. Metadata provided by Discovery Service is not cached,
+but requested each time you load a client. We're making changes to improve the
+situation for short-lived node processes. Below, there is an example of loading
+a client for [URL Shortener API](https://developers.google.com/url-shortener/).
+
+    googleapis.load('urlshortener', 'v1', function(err, client) {
+      if (!err) {
+        console.log('Client is loaded successfully');
+      }
+    });
+
+Alternatively, you may like to configure the client to append an API key to all
+requests you are going to make. Once you load a client library, you can set an
+API key:
+
+     googleapis.load('urlshortener', 'v1', function(err, client) {
+       client.withApiKey('YOUR API KEY HERE');
+       // make requestss
+     });
+
+To learn more about API keys, please see the [documentation](https://developers.google.com/console/help/#UsingKeys).
+
+### Requests
+
+Following sample loads a client for URL Shortener and retrieves the long url
+of the given short url:
+
+    googleapis.load('urlshortener', 'v1', function(err, client) {
+      // ...
       client
-        .newBatchRequest()
-        .add('urlshortener.url.get', { shortUrl: 'http://goo.gl/DdUKX' })
-        .add('urlshortener.url.insert', { longUrl: 'http://burcudogan.com' })
-        .execute(null, function(errs, results, headers){
-
+        .urlshortener
+        .url
+        .get({ shortUrl: 'http://goo.gl/DdUKX' })
+        .execute(function(err, result) {
+          // result.longUrl contains the long url.
         });
+    });
 
-      // a single request
+
+### Batch requests
+
+You can combine multiple requests in a single one by using batch requests.
+
+    googleapis.load('urlshortener', 'v1', function(err, client) {
+      // ...
+      var request1 =
+          client.urlshortener.url.get({ shortUrl: 'http://goo.gl/DdUKX' });
+      var request2 =
+          client.urlshortener.url.insert(null, { longUrl: 'http://goo.gl/A5492' });
+      // create from raw action name
+      var request3 = client.newRequest('urlshortener.url.list');
+
       client
-        .newRequest('urlshortener.url.get', { shortUrl1: 'http://goo.gl/DdUKX' })
-        .execute(null, function(err, result, headers){
+        .newBatchRequest()
+        .add(request1)
+        .add(request2)
+        .add(request3)
+        .execute(function(err, results) {
 
         });
+    });
 
-      // request builders
-      client.urlshortener.url
-        .get({ shortUrl: 'http://goo.gl/DdUKX' })
-        .execute();
+### Authorization and Authentication
+
+This client comes with an OAuth2 client allows you to retrieve an access token and
+refreshes the token and re-try the request seamlessly if token is expired. The
+basics of Google's OAuth 2.0 implementation is explained on
+[Google Authorization and Authentication
+documentation](https://developers.google.com/accounts/docs/OAuth2Login).
+
+A complete sample application that authorizes and authenticates with OAuth2.0
+client is available at `examples/ouath2.js`.
+
+#### Consent Page Url
+
+In order to ask for permissions from user to retrieve an access token, you
+should redirect them to a consent page. In order to create a consent page
+URL:
+
+    var googleapis = require('googleapis'),
+        OAuth2Client = googleapis.OAuth2Client;
+
+    var oauth2Client =
+        new OAuth2Client(CLIENT_ID, CLIENT_SECRET, REDIRECT_URL);
+
+    // generates a url allows offline access and asks permissions
+    // for Google+ scope.
+    var url = oauth2Client.generateAuthUrl({
+      access_type: 'offline',
+      scope: 'https://www.googleapis.com/auth/plus.me'
     });
 
+#### Retrieving Tokens
+Once user has given permissions on the consent page, Google will redirect
+the page to the redirect url you have provided with a code query parameter.
 
+    GET /oauthcallback?code={authorizationCode}
+
+With the code returned, you can ask for an access token as shown below:
+
+    oauth2Client.getToken(code, function(err, tokens) {
+      // contains an access_token and optionally a refresh_token.
+      // save them permanently.
+    });
+
+#### Making Authenticated Requests
+
+And you can start using oauth2Client to authorize and authenticate your
+requests to Google APIs with the retrieved tokens. If you provide a
+refresh_token, in cases when access_token is expired, it asks for a new
+access_token and replays the request.
+
+Following sample retrieves Google+ profile of the authenticated user.
+
+    oauth2Client.tokens = {
+      access_token = 'ACCESS TOKEN HERE',
+      refresh_token = 'REFRESH TOKEN HERE'
+    };
+
+    client
+      .plus.people.get({ userId: 'me' })
+      .withAuthClient(oauth2Client)
+      .execute(callback);
+
 ## License
 
-Copyright (c) 2012 Burcu Dogan
+`google-api-nodejs-client` is licensed with Apache 2.0. Full license text is
+available on COPYING file.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of
-this software and associated documentation files (the "Software"), to deal in
-the Software without restriction, including without limitation the rights to
-use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
-of the Software, and to permit persons to whom the Software is furnished to do
-so, subject to the following conditions:
+## Contributors
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+Before making any contributions, please sign one of the contributors
+licenses below.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
-FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
-COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Fork the repo, develop and test your code changes.
+
+Install all depedencies including development requirements by running:
+
+    $ npm install -d
+
+Install mocha globally to be able to run the tests.
+
+    $ npm install -g mocha
+
+To run the unit tests, use the following command. Ensure that your code has an
+appropriate set of unit tests which all pass.
+
+    $ mocha tests/*
+
+Your code should honor the
+[Google JavaScript Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml).
+You can use
+[Closure Linter](https://code.google.com/p/closure-linter/)
+to detect style issues.
+
+Submit a pull request. The repo owner will review your request. If it is
+approved, the change will be merged. If it needs additional work, the repo
+owner will respond with useful comments.
+
+#### Contributor License Agreements
+
+Before creating a pull request, please fill out either the individual or
+corporate Contributor License Agreement.
+
+* If you are an individual writing original source code and you're sure you
+own the intellectual property, then you'll need to sign an
+[individual CLA](http://code.google.com/legal/individual-cla-v1.0.html).
+* If you work for a company that wants to allow you to contribute your work
+to this client library, then you'll need to sign a
+[corporate CLA](http://code.google.com/legal/corporate-cla-v1.0.html).
+
+Follow either of the two links above to access the appropriate CLA and
+instructions for how to sign and return it. Once we receive it, we'll add you
+to the official list of contributors and be able to accept your patches.

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Filesystem access

Supply chain risk

Accesses the file system, and could potentially read sensitive data.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Wildcard dependency

Quality

Package has a dependency with a floating version range. This can cause issues if the dependency publishes a new major version.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

113595

increased by917.06%

Number of package files

20

increased by122.22%

Lines of code

2768

increased by810.53%

Number of medium quality alerts

0

decreased by-100%

Number of lines in readme file

212

increased by247.54%

Worsened metrics

Dev dependency count

2

increased byInfinity%

Number of low supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedrequest@2.14.0(transitive)

• - Removedajv@6.12.6(transitive)

• - Removedasn1@0.2.6(transitive)

• - Removedassert-plus@1.0.0(transitive)

• - Removedasynckit@0.4.0(transitive)

• - Removedaws-sign2@0.7.0(transitive)

• - Removedaws4@1.13.2(transitive)

• - Removedbcrypt-pbkdf@1.0.2(transitive)

• - Removedcaseless@0.12.0(transitive)

• - Removedcombined-stream@1.0.8(transitive)

• - Removedcore-util-is@1.0.2(transitive)

• - Removeddashdash@1.14.1(transitive)

• - Removeddelayed-stream@1.0.0(transitive)

• - Removedecc-jsbn@0.1.2(transitive)

• - Removedextend@3.0.2(transitive)

• - Removedextsprintf@1.3.0(transitive)

• - Removedfast-deep-equal@3.1.3(transitive)

• - Removedfast-json-stable-stringify@2.1.0(transitive)

• - Removedforever-agent@0.6.1(transitive)

• - Removedform-data@2.3.3(transitive)

• - Removedgetpass@0.1.7(transitive)

• - Removedhar-schema@2.0.0(transitive)

• - Removedhar-validator@5.1.5(transitive)

• - Removedhttp-signature@1.2.0(transitive)

• - Removedis-typedarray@1.0.0(transitive)

• - Removedisstream@0.1.2(transitive)

• - Removedjsbn@0.1.1(transitive)

• - Removedjson-schema@0.4.0(transitive)

• - Removedjson-schema-traverse@0.4.1(transitive)

• - Removedjson-stringify-safe@5.0.1(transitive)

• - Removedjsprim@1.4.2(transitive)

• - Removedmime-db@1.52.0(transitive)

• - Removedmime-types@2.1.35(transitive)

• - Removedoauth-sign@0.9.0(transitive)

• - Removedperformance-now@2.1.0(transitive)

• - Removedpsl@1.9.0(transitive)

• - Removedpunycode@2.3.1(transitive)

• - Removedqs@6.5.3(transitive)

• - Removedrequest@2.88.2(transitive)

• - Removedsafe-buffer@5.2.1(transitive)

• - Removedsafer-buffer@2.1.2(transitive)

• - Removedsshpk@1.18.0(transitive)

• - Removedtough-cookie@2.5.0(transitive)

• - Removedtunnel-agent@0.6.0(transitive)

• - Removedtweetnacl@0.14.5(transitive)

• - Removeduri-js@4.4.1(transitive)

• - Removeduuid@3.4.0(transitive)

• - Removedverror@1.10.0(transitive)

• Updatedrequest@2.14.0