Merge pull request #3 from Ramblurr/master

Update ember-cli and keen.js, and some new goodies

.npmignore

@@ -1,12 +1,16 @@
-bower_components/
-tests/
-tmp/
-
+/bower_components
+/config/ember-try.js
+/dist
+/tests
+/tmp
+**/.gitkeep
 .bowerrc
 .editorconfig
 .ember-cli
+.gitignore
+.jshintrc
+.watchmanconfig
 .travis.yml
-.npmignore
-**/.gitkeep
-Brocfile.js
+bower.json
+ember-cli-build.js
 testem.json

.watchmanconfig

@@ -0,0 +1,3 @@
+{
+  "ignore_dirs": ["tmp", "dist"]
+}

CHANGELOG.md

@@ -0,0 +1,24 @@
+# Ember Keen Querying Changelog
+
+## \[Unreleased\]
+
+**Update Notes**: none
+
+### Added
+- This [CHANGELOG.md](CHANGELOG.md)
+- Documentation to the KeenQueryingService
+- `.collectionsAll()` method to fetch all event collections
+- `.collection()` method to fetch a single event collections
+
+### Changed
+- Added tmp dir to `.npmignore` (thanks @odoe)
+- Updated to keen.ks 3.4.0
+- Updated to ember-cli 2.3.0
+
+## [0.0.7] - 2015-05-14
+### Changed
+- Using bower to import keen.js
+- Other things, lost to time.
+
+## [0.0.1] - 2015-05-12
+- initial release

LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015
+Copyright (c) 2016
 
 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:
 

README.md

@@ -1,30 +1,41 @@
 [![Build Status](https://travis-ci.org/plyfe/ember-keen-querying.svg?branch=master)](https://travis-ci.org/plyfe/ember-keen-querying) [![Ember Observer Score](http://emberobserver.com/badges/ember-keen-querying.svg)](http://emberobserver.com/addons/ember-keen-querying)
 
-# ember-keen-querying
+# Ember Keen Querying
 
-ember-keen-querying is an easy way to query events in Keen IO in your ember-cli project. A simple Ember service wraps the [keen-js SDK](https://github.com/keen/keen-js) and can be injected anywhere in your application.
+An easy way to query Keen.io data from your Ember CLI App.
 
-To track Keen IO events in ember, see the sister addon: [ember-keen-tracking](https://github.com/plyfe/ember-keen-tracking)
+---
+
+ember-keen-querying is addon that provides an Ember service wrapping the [keen-js SDK](https://github.com/keen/keen-js). Since it is a service, it can injected and used anywhere in your application.
+
+It exposes querying and analysis APIs to run simple and advanced queries using the keen.js API.
+
+**Want to Track Events?**
+To track Keen.io events in Ember, see the sister addon: [ember-keen-tracking](https://github.com/plyfe/ember-keen-tracking)
 
-We welcome contributions!
 
 ## Installation
 
-`ember install:addon ember-keen-querying`<br>
-`ember generate ember-keen-querying`
+```sh
+ember install ember-keen-querying    # install:addon for Ember CLI < 0.2.3
+ember generate ember-keen-querying
+```
 
-## Setup
+##  Updating
 
-A Keen project id and read key is required to track events. You can set these api keys in one of 3 ways:
+This project is new and the API is subject to change. When updating your project to a newer version of ember-keen-querying, please consult the [changelog](CHANGELOG.md) for any update notes.
 
-1. Set a `KEEN_PROJECT_ID` and `KEEN_READ_KEY` on `ENV` in `config/environment`. The [ember-cli-dotenv](https://github.com/fivetanley/ember-cli-dotenv) addon is a safe and easy way to do this.
+## Getting Started
+
+A Keen project id and read key is required to query events. You can set these api keys in one of 3 ways:
 
-2. A metatag of the form: `<meta property="keen:project_id" content="[KEEN_PROJECT_ID]" />`
+1. Set a `KEEN_PROJECT_ID` and `KEEN_READ_KEY` on `ENV` in `config/environment`. The [ember-cli-dotenv](https://github.com/fivetanley/ember-cli-dotenv) addon is a safe and easy way to do this.
 
-3. Set a global `KEEN_PROJECT_ID`.
+2. A meta tag of the form: `<meta property="keen:project_id" content="[KEEN_PROJECT_ID]" />`
 
-## Usage
+3. Set a global `KEEN_PROJECT_ID`
 
+## Basic Usage
 *The Ember.Service class is only supported in Ember 1.11+. If your application is on an older version of Ember, you can achieve the same effect of this addon by injecting the service as an Ember object through an initializer.*
 
 You can inject and use the service anywhere like so:

addon/services/keen-querying.js

@@ -1,47 +1,111 @@
 /* global Keen */
+import Ember from 'ember';
+import config from 'ember-get-config';
 
-// See keen-js SDK's query events docs for more info:
-// https://github.com/keen/keen-js/blob/master/docs/query.md#run-multiple-analyses-at-once
+const {
+  Service,
+  Logger,
+  RSVP,
+  computed,
+  typeOf,
+  isBlank
+  } = Ember;
 
-import Ember from 'ember';
+/**
+ *  An Ember service for Keen.io that exposes querying and extraction APIs using the keen.js library.
+ *
+ * See [keen-js SDK's docs](https://github.com/keen/keen-js) for more info.
+ *
+ * @module keen-querying
+ * @namespace Service
+ * @class KeenQuerying
+ * @extends Ember.Service
+ */
+export default Service.extend({
+  env: computed(function () {
+    return config;
+  }),
 
-export default Ember.Service.extend({
-  env: function() {
-    return this.container.lookupFactory('config:environment');
-  }.property(),
-  projectId: function() {   // String (required always)
-    var projectId = this.get('env').KEEN_PROJECT_ID || Ember.$('meta[property="keen:project_id"]').attr('content') || window.KEEN_PROJECT_ID;
-    if (!projectId) {
-      Ember.Logger.info('Ember Keen Querying: Missing Keen project id, please set `ENV.KEEN_PROJECT_ID` in config.environment.js');
+  /**
+   * The Keen Project ID
+   * @required
+   * @property
+   * @type String
+   */
+  projectId: computed('env', function () {
+    let projectId = this.get('env').KEEN_PROJECT_ID || Ember.$('meta[property="keen:project_id"]').attr('content') || window.KEEN_PROJECT_ID;
+    if (isBlank(projectId)) {
+      Logger.info('Ember Keen Querying: Missing Keen project id, please set ENV.KEEN_PROJECT_ID in config.environment.js');
     }
     return projectId;
-  }.property('env'),
-  readKey: function() {     // String (required for sending data)
+  }),
+
+
+  readKey: computed('env', function () {   // String (required for sending data)
     var readKey = this.get('env').KEEN_READ_KEY || Ember.$('meta[property="keen:read_key"]').attr('content') || window.KEEN_READ_KEY;
-    if (!readKey) {
-      Ember.Logger.info('Ember Keen Querying: Missing Keen read key, please set `ENV.KEEN_READ_KEY` in config.environment.js');
+    if (isBlank(readKey)) {
+      Logger.info('Ember Keen Querying: Missing Keen read key, please set ENV.KEEN_READ_KEY in config.environment.js');
     }
     return readKey;
-  }.property('env'),
-  protocol: "auto",         // String (optional: https | http | auto)
-  host: "api.keen.io/3.0",  // String (optional)
-  requestType: null,        // String (optional: jsonp, xhr, beacon)
+  }),
+
+  /**
+   * Allowed values: https | http | auto
+   * @property protocol
+   * @default "auto"
+   * @optional
+   * @type String
+   */
+  protocol: "auto",
+  /**
+   * @property host
+   * @default "api.keen.io/3.0"
+   * @optional
+   * @type String
+   */
+  host: "api.keen.io/3.0",
+  /**
+   * Allowd values: null, jsonp, xhr, beacon
+   * @property requestType
+   * @default null, decided by the Keen library
+   * @optional
+   * @type null|String
+   */
+  requestType: null,
 
-  client: function() {
+  /**
+   * The Keen client object, configured and ready to go.
+   * @property client
+   */
+  client: computed('projectId', 'readKey', 'protocol', 'host', 'requestType', function () {
     return new Keen({
       projectId: this.get('projectId'),
       readKey: this.get('readKey'),
       protocol: this.get('protocol'),
       host: this.get('host'),
       requestType: this.get('requestType')
     });
-  }.property('projectId', 'readKey', 'protocol', 'host', 'requestType'),
+  }),
 
-  query: function(analysisType, eventOrParams) {
-    var self = this;
+  /**
+   * Query a single event collection or extraction.
+   *
+   * @example
+   *     keenQuerying.query('count', {
+   *         event_collection: "pageviews",
+   *         timeframe: {
+   *           "start":"2015-07-01T07:00:00.000Z",
+   *           "end":"2015-08-01T07:00:00.000Z"
+   *      }).then(...)
+   *
+   * @param analysisType
+   * @param eventOrParams
+   * @returns {RSVP.Promise}
+   */
+  query: function (analysisType, eventOrParams) {
     var analysis = this._prepareAnalysis(analysisType, eventOrParams);
-    return new Ember.RSVP.Promise(function(resolve, reject) {
-      self.get('client').run(analysis, function(err, res){
+    return new RSVP.Promise((resolve, reject) => {
+      this.get('client').run(analysis, (err, res) => {
         if (err) {
           reject(err);
         }
@@ -52,17 +116,23 @@ export default Ember.Service.extend({
     });
   },
 
-  // argument structure = {{analysisType1: eventOrParams1}, {analysisType2: eventOrParams2}, ...}
-  // https://github.com/keen/keen-js/blob/master/docs/query.md#run-multiple-analyses-at-once
-  multiQuery: function(queriesData) {
-    var self = this;
+  //
+  /**
+   * TODO : fix these docs
+   *  See [keen-js SDK's query events docs](https://github.com/keen/keen-js/blob/master/docs/query.md#run-multiple-analyses-at-once) for more info.
+   *
+   * argument structure = {{analysisType1: eventOrParams1}, {analysisType2: eventOrParams2}, ...}
+   * @param queriesData a nested object of
+   * @returns {RSVP.Promise}
+     */
+  multiQuery: function (queriesData) {
     var analyses = [];
     for (var key in queriesData) {
       var newAnalysis = this._prepareAnalysis(key, queriesData[key]);
       analyses.push(newAnalysis);
     }
-    return new Ember.RSVP.Promise(function(resolve,reject) {
-      self.get('client').run(analyses, function(err, res) {
+    return new RSVP.Promise((resolve, reject) => {
+      this.get('client').run(analyses, (err, res) => {
         if (err) {
           reject(err);
         }
@@ -73,11 +143,56 @@ export default Ember.Service.extend({
     });
   },
 
-  _prepareAnalysis: function(analysisType, eventOrParams) {
+  /**
+   * Inspect all event collections in the project and their properties.
+   * @method
+   * @returns {Ember.RSVP.Promise}
+   */
+  collectionsAll: function() {
+    return new Ember.RSVP.Promise((resolve,reject) => {
+      let url = this.get('client').url('/events');
+      this.get('client').get(url, null, this.get('client').readKey(), (err, res) =>{
+        if (err) {
+          reject(new Error(err));
+        }  else {
+          resolve(res);
+        }
+      });
+    });
+  },
+
+  /**
+   * Inspect a single event collection and its properties.
+   * @method
+   * @param collection_name the name of the event collection to inspect
+   * @returns {Ember.RSVP.Promise}
+   */
+  collection: function(collection_name) {
+    return new Ember.RSVP.Promise((resolve,reject) => {
+      let url = this.get('client').url(`/events/${collection_name}`);
+      this.get('client').get(url, null, this.get('client').readKey(), (err, res) =>{
+        if (err) {
+          reject(new Error(err));
+        }  else {
+          resolve(res);
+        }
+      });
+    });
+  },
+
+  /**
+   * Creates the Keen.Query object from parameters
+   * @param analysisType
+   * @param eventOrParams a bare event string or collection of params.
+   * @returns {Keen.Query}
+   * @private
+   */
+  _prepareAnalysis: function (analysisType, eventOrParams) {
     var params = eventOrParams;
-    if (Ember.typeOf(eventOrParams) === 'string') {
-      params = { eventCollection: eventOrParams };
+    if (typeOf(eventOrParams) === 'string') {
+      params = {eventCollection: eventOrParams};
     }
     return new Keen.Query(analysisType, params);
   }
 });
+

app/services/keen-querying.js

@@ -1,2 +1 @@
-import KeenQueryingService from 'ember-keen-querying/services/keen-querying';
-export default KeenQueryingService.extend();
+export { default } from 'ember-keen-querying/services/keen-querying';

blueprints/ember-keen-querying/index.js

@@ -1,10 +1,7 @@
-
-'use strict';
-
 module.exports = {
   normalizeEntityName: function() {},
 
   afterInstall: function() {
-    return this.addBowerPackagesToProject([{ name: 'keen-js', target: '3.2.4'}]);
+    return this.addBowerPackagesToProject([{ name: 'keen-js', target: '~3.4.0'}]);
   }
 };