google-adwords - npm Package Compare versions

Comparing version 0.0.1 to 1.0.0

package.json

 {
   "name": "google-adwords",
-  "version": "0.0.1",
-  "description": "A Node.js driver for Google Adwords API (v201409)",
+  "version": "1.0.0",
+  "description": "A Node.js driver for Google Adwords Reporting API (v201409)",
   "main": "lib/googleadwords.js",
@@ -24,3 +24,15 @@ "scripts": {
   },
-  "homepage": "https://github.com/Growmies/google-adwords"
+  "homepage": "https://github.com/Growmies/google-adwords",
+  "dependencies": {
+    "adwords-auth": "0.0.10",
+    "bluebird": "^2.9.12",
+    "lodash": "^3.3.0",
+    "moment": "^2.9.0",
+    "unirest": "^0.4.0",
+    "xml2js": "^0.4.5"
+  },
+  "devDependencies": {
+    "chai": "^2.0.0",
+    "mocha": "^2.1.0"
+  }
 }

README.md

 # google-adwords
-A Node.js driver for Google Adwords API (v201409)
+[![npm](https://img.shields.io/npm/dm/google-adwords.svg)](https://www.npmjs.com/package/google-adwords)
+[![Code Climate](https://img.shields.io/codeclimate/coverage/github/Growmies/google-adwords.svg)](https://codeclimate.com/github/Growmies/google-adwords)
+
+A Node.js driver for Google Adwords Reporting API (v201409)
+
+## Contents
+- [Install](#install)
+- [API](#api)
+  - [`.use()`](#useoptions)
+  - [`.awql()`](#awql)
+    - [chaining](#chaining)
+    - [options](#options)
+    - [string](#string)
+  - [Returns](#returns)
+  - [error handling](#error-handling)
+    - [.`catch()`](#catch)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+- [License (ISC)](#license-isc)
+
+## Install
+
+To install google-adwords, run
+
+```bash
+npm install google-adwords
+```
+
+then include in your file the following:
+
+```javascript
+var ga = require('google-adwords');
+```
+
+## API
+
+### `.use(options)`
+
+This function is used to set client access information, specifically the `clientID`, the `clientSecret` and the `developerToken` fields. This is also used prior to each call to set the `clientCustomerID` and the `refreshToken`.
+
+Any call to Google Adwords automatically refreshes the accessToken for the call. This may be overridden by including both the `accessToken` and the `tokenExpires` in the user setting along with the `clientCustomerID` and the `refreshToken`.
+
+```javascript
+  ga.use({
+    clientID: 'clientIDString',
+    clientSecret: 'clientSecretString',
+    developerToken: 'developerTokenString'
+  });
+  // Sets Client options for usage in your app.
+```
+
+```javascript
+  ga.use({
+    refreshToken: 'refreshTokenString',
+    clientCustomerID: 'clientCustomerIDString'
+  });
+  // Sets user options if you wish to refresh the token on every call.
+```
+
+```javascript
+  ga.use({
+    accessToken: 'accessTokenString',
+    tokenExpires: 1424716834341, // Integer: Unix Timestamp of expiration time
+    refreshToken: 'refreshTokenString',
+    clientCustomerID: 'clientCustomerIDString'
+  });
+  // Sets user options if you do not wish to refresh every call. Will refresh if expiration is hit.
+```
+
+### `.awql()`
+
+Once the appropriate access information has been set with `.use()`, you may use `.awql()` to make calls to your reports. You may do this in a number of ways: chaining, options object, or AWQL string. All options return a Bluebird promise, with `.then()` and `.catch` for successful and failing use cases, respectively.
+
+#### chaining
+
+To use `.awql()` chaining, simply chain additional keywords onto your query like this:
+
+```javascript
+ga.awql()
+  .select('Date,Clicks')
+  .from('ACCOUNT_PERFORMANCE_REPORT')
+  .during('20120101,20150125')
+  .send().then(function(results) {
+    // your code here
+  })
+```
+
+Alternatively, you can pass arrays into `.select()` and `.during()`:
+
+```javascript
+ga.awql()
+  .select(['Date','Clicks'])
+  .from('ACCOUNT_PERFORMANCE_REPORT')
+  .during(['20120101','20150125'])
+  .send().then(function(results) {
+    // your code here
+  })
+```
+
+You may also add a `.where()` and a `.and()` into the chain after `.from()`, allowing for drilling of information:
+
+```javascript
+ga.awql()
+  .select(['Date', 'Clicks'])
+  .from('ACCOUNT_PERFORMANCE_REPORT')
+  .where('Clicks>100')
+  .during(['20120101', '20150125'])
+  .send().then(function(results) {
+    // your code here
+  })
+```
+```javascript
+ga.awql()
+  .select(['Date', 'Clicks'])
+  .from('ACCOUNT_PERFORMANCE_REPORT')
+  .where('Clicks>100')
+  .and('Clicks<200')
+  .during(['20120101', '20150125'])
+  .send().then(function(results) {
+    // your code here
+  })
+```
+
+You can chain additional `.and() functions after the first:
+
+```javascript
+ga.awql()
+  .select(['Date', 'Clicks'])
+  .from('ACCOUNT_PERFORMANCE_REPORT')
+  .where('Clicks>100')
+  .and('Clicks<200')
+  .and('Clicks!=110')
+  .during(['20120101', '20150125'])
+  .send().then(function(results) {
+    // your code here
+  })
+```
+
+Alternatively, you can pass an array of `.and()` statements into the first:
+
+```javascript
+ga.awql()
+  .select(['Date', 'Clicks'])
+  .from('ACCOUNT_PERFORMANCE_REPORT')
+  .where('Clicks>100')
+  .and(['Clicks<200','Clicks!=110'])
+  .during(['20120101', '20150125'])
+  .send().then(function(results) {
+    // your code here
+  })
+```
+
+#### options
+
+You can also access the reports by passing an object into `.awql()` as such:
+
+```javascript
+var options = {
+  select: ['Date', 'Clicks'],
+  from: 'ACCOUNT_PERFORMANCE_REPORT',
+  during: ['20120101', '20150125']
+}
+ga.awql(options).send().then(function(results) {
+  expect(results).to.be.an('object');
+  expect(results.report).to.be.a('string');
+  expect(results.total).to.be.a('string');
+  expect(results.data).to.be.an('array');
+  done();
+})
+```
+
+As with the promises above, you may pass both strings or arrays to `select`, `and`, and `during`.
+
+#### string
+
+Finally, you can pass your own AWQL string into `.awql`. Make sure there are no spaces in your `where` statements, as this string will replace all spaces (besides `, `) with `+` for proper API sending.
+
+```javascript
+var awqlStatement = 'SELECT Date, Clicks FROM ACCOUNT_PERFORMANCE_REPORT DURING 20120101, 20150125'
+ga.awql(awqlStatement).send().then(function(results) {
+  // your code here
+});
+```
+
+### Returns
+
+All request return information in the following format:
+
+```javascript
+{
+  report:'Title of the Report',
+  timeframe: 'Timeframe of the report',
+  total: 'Overall total of the report',
+  fieldLength: 7, // Integer: The number of fields (columns) that are being returned
+  data:[] // contains objects of individual report rows returned
+  auth:{ // This is the updated auth from the request. You may pipe this back in using ga.use()
+    accessToken:'accessTokenString',
+    tokenExpires: 1424716834341, // Integer: Unix Timestamp of expiration time
+  }
+}
+```
+
+### Error Handling
+
+All `.awql()` calls return two promise chains, `.then()` and `.catch()` as outlined in the [Bluebird documentation](https://github.com/petkaantonov/bluebird). You may use `.catch()` to catch any issues that may have arisen in the call.
+
+#### `.catch()`
+
+```javascript
+ga.awql()
+  .select(['DateRUBBISH', 'ClicksFAKE']) // selecting invalid fields
+  .from('ACCOUNT_PERFORMANCE_REPORT')
+  .during(['20120101', '20150125'])
+  .send().then(function(results) {
+    // this will not run
+  })
+  .catch(function(error) {
+    // error handling code here
+  })
+```
+
+## Contributing
+
+To contribute, fork the repo, and make sure to install dev dependencies using
+```bash
+npm install --dev
+```
+
+Make sure all changes have been updated/added in the `test/` folder, and, making sure you have [`mocha` installed globally](http://mochajs.org/#installation), run:
+
+```bash
+mocha
+```
+
+which should return without any errors. Additionally, make sure you have checked the test coverage for your change, by [installing `istanbul` globally](https://github.com/gotwarlost/istanbul#getting-started), then running:
+
+```bash
+istanbul cover _mocha --
+```
+You can then find the coverage report in `coverage/lcov-report/index.html`.
+
+After making changes in your fork, open a pull request.
+
+## Changelog
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/) and [Keep A Changelog](http://keepachangelog.com/).
+
+### Unreleased
+
+### v1.0.0 - 2015-02-23
+#### Added
+
+- `.use()`
+- `.awql()`
+- Tests
+
+## License (ISC)
+
+Copyright (c) 2015, Trent Oswald (therebelrobot)
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

New alerts

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

Empty package

Supply chain risk

Package does not contain any code. It may be removed, is name squatting, or the result of a faulty package publish.

Found 1 instance in 1 package

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

35924

increased by2773.92%

Number of package files

7

increased by133.33%

Lines of code

774

increased byInfinity%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

265

increased by8733.33%

Worsened metrics

Dependency count

6

increased byInfinity%

Dev dependency count

2

increased byInfinity%

Number of low supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedadwords-auth@0.0.10

• + Addedbluebird@^2.9.12

• + Addedlodash@^3.3.0

• + Addedmoment@^2.9.0

• + Addedunirest@^0.4.0

• + Addedxml2js@^0.4.5

• + Addedadwords-auth@0.0.10(transitive)

• + Addedasn1@0.1.11(transitive)

• + Addedassert-plus@0.1.5(transitive)

• + Addedasync@0.9.2(transitive)

• + Addedaws-sign2@0.5.0(transitive)

• + Addedbl@0.9.5(transitive)

• + Addedbluebird@2.11.0(transitive)

• + Addedboom@0.4.2(transitive)

• + Addedcaseless@0.8.0(transitive)

• + Addedcombined-stream@0.0.7(transitive)

• + Addedcore-util-is@1.0.3(transitive)

• + Addedcryptiles@0.2.2(transitive)

• + Addedctype@0.5.3(transitive)

• + Addeddelayed-stream@0.0.5(transitive)

• + Addedforever-agent@0.5.2(transitive)

• + Addedform-data@0.2.0(transitive)

• + Addedhawk@1.1.1(transitive)

• + Addedhoek@0.9.1(transitive)

• + Addedhttp-signature@0.10.1(transitive)

• + Addedinherits@2.0.4(transitive)

• + Addedisarray@0.0.1(transitive)

• + Addedjson-stringify-safe@5.0.1(transitive)

• + Addedlodash@3.10.1(transitive)

• + Addedmime@1.2.11(transitive)

• + Addedmime-db@1.12.0(transitive)

• + Addedmime-types@1.0.22.0.14(transitive)

• + Addedmoment@2.30.1(transitive)

• + Addednode-uuid@1.4.8(transitive)

• + Addedoauth-sign@0.5.0(transitive)

• + Addedopen@0.0.5(transitive)

• + Addedqs@2.3.3(transitive)

• + Addedreadable-stream@1.0.34(transitive)

• + Addedrequest@2.51.0(transitive)

• + Addedsax@1.4.1(transitive)

• + Addedsntp@0.2.4(transitive)

• + Addedstring_decoder@0.10.31(transitive)

• + Addedstringstream@0.0.6(transitive)

• + Addedtldts@6.1.77(transitive)

• + Addedtldts-core@6.1.77(transitive)

• + Addedtough-cookie@5.1.1(transitive)

• + Addedtunnel-agent@0.4.3(transitive)

• + Addedunirest@0.4.2(transitive)

• + Addedxml2js@0.4.23(transitive)

• + Addedxmlbuilder@11.0.1(transitive)