1 /**
  2  * @overview <p>Spire API Client</p>
  3  *
  4  * <p>spire.io.js is a library designed to help you get your client-side web
  5  * applications up and running with the high level services provided by the
  6  * spire.io API. This plugin also exposes a methodology for directly interfacing
  7  * with the spire.io REST interface.</p>
  8  *
  9  * <p>You can learn more about spire.io and it's services at http://spire.io, or
 10  * find help with the following things:</p>
 11  *
 12  * <ul>
 13  *   <li>source code: http://github.com/spire-io/spire.io.js</li>
 14  *   <li>issues: http://github.com/spire-io/spire.io.js/issues</li>
 15  *   <li>contact: http://spire.io/contact.htms</li>
 16  * </ul>
 17  */
 18 
 19 var API = require('./spire/api')
 20   , Shred = require('shred')
 21   ;
 22 
 23 /**
 24  * Spire API Client
 25  *
 26  * @class <strong>Spire API Client</strong>
 27  *
 28  * @example
 29  * var spire = new Spire();
 30  *
 31  * @example
 32  * var spire = new Spire({
 33  *   secret: my_account_secret
 34  * });
 35  *
 36  * @constructor
 37  * @param {object} [opts] Options for Spire
 38  * @param {string} [secret] The account API secret.  If you do you not set this, you
 39  * must call one of:
 40  *   * `spire.start(secret, callback)`
 41  *   * `spire.login(email, password, callback)` or
 42  *   * `spire.register(user, callback)
 43  *   before you can start creating channels.
 44  * @param {string} [opts.url] Spire url do use (defaults to 'https://api.spire.io')
 45  * @param {string} opts.version Version of Spire api to use (defaults to '1.0')
 46  * @param {boolean} opts.logCurl Log all requests as curl commands (defaults to false)
 47  */
 48 function Spire(opts) {
 49   opts = opts || {};
 50 
 51   /**
 52    * Spire API resource.
 53    * Contains low-level methods for interfacing with the Spire.io API.
 54    */
 55   this.api = new API(this, opts);
 56 
 57   /**
 58    * Spire session.
 59    * Contains methods for creating channels, subscriptions, and applications.
 60    */
 61   this.session = null;
 62 
 63   /**
 64    * Shred.
 65    * The HTTP client used by the spire.io.js library.
 66    */
 67   this.shred = new Shred({
 68     logCurl: opts.logCurl
 69   });
 70 }
 71 
 72 module.exports = Spire;
 73 
 74 /**
 75  * Start the Spire session with the given account secret.
 76  *
 77  * @example
 78  * var spire = new Spire();
 79  * spire.start(your_api_secret, function (err, session) {
 80  *   if (!err) {
 81  *     // `session` is a spire session.
 82  *     // Start creating channels and subscripions.
 83  *   }
 84  * });
 85  *
 86  * @param {string} secret The acccount secret
 87  * @param {function(err, session)} cb Callback
 88  */
 89 Spire.prototype.start = function (secret, cb) {
 90   var spire = this;
 91   this.api.createSession(secret, function (err, session) {
 92     if (err) return cb(err);
 93     spire.session = session;
 94     cb(null, session);
 95   });
 96 };
 97 
 98 /**
 99  * Start the Spire session with the given username and password.
100  *
101  * @example
102  * var spire = new Spire();
103  * spire.login(your_email, your_password, function (err, session) {
104  *   if (!err) {
105  *     // `session` is a spire session.
106  *     // Start creating channels and subscripions.
107  *   }
108  * });
109  *
110  * @param {string} email Email
111  * @param {string} password Password
112  * @param {function(err, session)} cb Callback
113  */
114 Spire.prototype.login = function (email, password, cb) {
115   var spire = this;
116   this.api.login(email, password, function (err, session) {
117     if (err) return cb(err);
118     spire.session = session;
119     cb(null, session);
120   });
121 };
122 
123 /**
124  * Retrieve an application with a given application key.
125  *
126  * @example
127  * var spire = new Spire();
128  * spire.getApplication('key-for-your-app', function (err, application) {
129  *   if (!err) {
130  *     // 'application' will now hold your application object.
131  *   }
132  * });
133  *
134  * @param {string} application_key Application key
135  * @param {function(err, application)} cb Callback
136  */
137 Spire.prototype.getApplication = function (application_key, cb) {
138   var spire = this;
139   this.api.getApplication(application_key, function (err, application) {
140     if (err) return cb(err);
141     cb(null, application);
142   });
143 };
144 
145 /**
146  * Registers for a new spire account, and authenticates as the newly created account
147  *
148  * @example
149  * var spire = new Spire();
150  * spire.register({
151  *   email: your_email,
152  *   password: your_password,
153  *   password_confirmation: your_password_confirmation
154  * }, function (err) {
155  *   if (!err) {
156  *     // Your account has been registered.
157  *     // `session` is a spire session.
158  *     // Start creating channels and subscripions.
159  *   }
160  * });
161  *
162  * @param {object} user User info
163  * @param {string} user.email Email
164  * @param {string} user.password Password
165  * @param {string} [user.password_confirmation] Optional password confirmation
166  * @param {function (err, session)} cb Callback
167  */
168 Spire.prototype.register = function (user, cb) {
169   var spire = this;
170   this.api.createAccount(user, function (err, session) {
171     if (err) return cb(err);
172     spire.session = session;
173     cb(null, session);
174   });
175 };
176 
177 /**
178  * Requests a password reset for email.
179  *
180  * @example
181  * var spire = new Spire();
182  * spire.passwordResetRequest(your_email, function (err) {
183  *   if (!err) {
184  *     // A password reset email has been sent.
185  *   }
186  * });
187  *
188  * @param {string} email Email
189  * @param {function (err)} cb Callback
190  */
191 Spire.prototype.passwordResetRequest = function (email, cb) {
192   this.api.passwordResetRequest(email, cb);
193 };
194 
195 /**
196  * Number of times to retry creating a channel or subscription before giving up.
197  */
198 Spire.prototype.CREATION_RETRY_LIMIT = 5;
199