Merge remote-tracking branch 'origin/jsdoc-wip' into jsdoc-wip

* origin/jsdoc-wip:
  updated readme
  mention proxies tenant methods

README.md

@@ -7,105 +7,134 @@
 
 *A simple user management library for Node.js.*
 
-[Stormpath](https://stormpath.com) is a complete user management API.  This
-library gives your Node app access to all of Stormpath's features:
+This library is a wrapper for the [Stormpath][] REST API.  It is a collection of
+methods that allow you to create, modify, and update resources in the REST API,
+without having to manually make HTTP calls from your own code.
+
+[Stormpath][] is a User Management API that reduces development time with instant-
+on, scalable user infrastructure. Stormpath's intuitive API and expert support
+make it easy for developers to authenticate, manage and secure users and roles
+in any application.
+
+This library provides low-level access to all of Stormpath's features, to name
+a few:
 
 - Robust authentication and authorization.
 - Schemaless user data.
-- Pre-built or hosted login screens.
 - Social login with Facebook and Google OAuth.
 - Generate and manage API keys for your service.
+- Stateless authentication with JWTs.
 
-If you have feedback about this library, please get in touch and share your
-thoughts! support@stormpath.com
-
-[Stormpath](https://stormpath.com) is a User Management API that reduces
-development time with instant-on, scalable user infrastructure.  Stormpath's
-intuitive API and expert support make it easy for developers to authenticate,
-manage, and secure users and roles in any application.
+Because this library gives you basic low-level access to the REST API only, it
+may not always be the best choice for the problem that you are trying to solve.
+If you want to work with a more comprehensive framework integration, please see
+the other libraries that are listed below.
 
 
 ## Documentation
 
-All of this library's documentation can be found here:
-http://docs.stormpath.com/nodejs/api/home (*It's ridiculously easy to get
-started with.*)
+This library is fully documented with JsDoc, please visit the site here:
+[Stormpath Node.js SDK Documentation][]
 
 
-## Links
-
-Below are some resources you might find useful!
+## Install
 
-- [Quickstart](http://docs.stormpath.com/nodejs/quickstart/)
-- [Stormpath Node.js API Documentation](http://docs.stormpath.com/nodejs/api)
+```bash
+npm install stormpath
+```
 
-**Express-Stormpath**
 
-- [Express-Stormpath Integration](https://github.com/stormpath/stormpath-express)
-- [Express-Stormpath Docs](https://docs.stormpath.com/nodejs/express/)
-- [15-Minute Tutorial: Build a Webapp with Node, Express, Bootstrap & Stormpath](https://stormpath.com/blog/build-nodejs-express-stormpath-app/)
-- [Deploy Stormpath on Heroku with Express.js](https://github.com/stormpath/stormpath-heroku-express-sample)
+## Usage
 
-**Passport-Stormpath**
+Everything starts with a [Client][] instance, which you create like so:
 
-- [Stormpath Passport Strategy](https://github.com/stormpath/passport-stormpath)
-- [stormpath-passport-express Sample App repo](https://github.com/stormpath/stormpath-passport-express-sample)
-- [Stormpath Passport Docs](https://docs.stormpath.com/nodejs/passport/)
-- [15-Minute Tutorial: Build a Webapp With Node.js, Express, Passport and Stormpath](https://stormpath.com/blog/build-app-nodejs-express-passport-stormpath/)
+```
+// Assumes API keys are in environment variables, or stormpath.yaml
 
+var stormpath = require('stormpath');
 
-## Install
-
-```bash
-npm install stormpath
+var client = new stormpath.Client();
 ```
 
+With a [Client][] instance, you can do many operations, like fetching all of the
+accounts in your Stormpath Tenant:
 
-## Quickstart
+```
+// Fetch all the accounts in my Stormpath Tenant
+
+client.getAccounts(function(err, accountsCollection) {
+  accountsCollection.each(function(account, next) {
+    console.log(account);
+    next();
+  });
+});
+```
 
-The Quickstart is on the front page of the [Stormpath Node.js API Documentation](http://docs.stormpath.com/nodejs/api).
 
+## Other Libraries
 
-## Building
+This library is a low-level wrapper for the [Stormpath][] REST API.  We also
+provide high-level libraries for popular frameworks, these libraries provide
+default views for login and registration, as well as many other features for
+adding authentication and authorization to your full-stack web or mobile
+application.
 
-This code does not require a build step and can be immediately required by your node application after installed from npm (see above).
+- [Express-Stormpath][] - A deep integration with Express that will add default
+  view for authentication, and provide a JSON API for front-end and mobile
+  clients to use for authentication.
 
-You may run the unit tests via npm:
+- [Stormpath Angular SDK][] - This library provides default login and registration
+  views in your Angular application, and communicates with [Express-Stormpath][]
+  via its JSON API to authenticate the user, and tell Angular about the logged-in
+  user.  This library can be used with other back-end frameworks, for more
+  integrations see https://docs.stormpath.com
 
-```bash
-npm test
-```
+- [Stormpath React SDK][] - This library provides routes and components for
+  React that will allow you to solve common user management tasks using Stormpath,
+  such as login and signup.  It communicates with [Express-Stormpath][] via
+  its JSON API to authenticate the user and provide user context to your React
+  application.  This library can be used with other back-end frameworks, for more
+  integrations see https://docs.stormpath.com
 
-To build the documentation, you need to enter the `docs` directory, then run:
 
-```console
-$ npm install -g bower
-$ npm install
-$ bower install
-$ grunt
-```
+## Tutorials
 
-The `grunt serve` command will build and serve the docs locally on port 9000.  You can
-view the HTML documentation by visiting http://localhost:9000/home in your browser.
+These guides will walk you through the creation of a full-stack JavaScript
+application that uses Node.js:
 
+- [API Key Management for Node – A Sample App](https://stormpath.com/blog/easy-api-key-management-for-node-a-sample-app-2)
+- [Build an API Service with Oauth2 Authentication, using Restify and Stormpath](https://stormpath.com/blog/build-api-restify-stormpath)
+- [Build an app with AngularJS, Node.js and Stormpath in 15 minutes](https://stormpath.com/blog/angular-node-15-minutes)
+- [Build a React.js Application with User Authentication](https://stormpath.com/blog/build-a-react-app-with-user-authentication)
+- [Build a REST API for Your Mobile Apps using Node.js](https://stormpath.com/blog/tutorial-build-rest-api-mobile-apps-using-node-js)
+- [Build a Webapp with Node, Express, Bootstrap & Stormpath](https://stormpath.com/blog/build-nodejs-express-stormpath-app/)
+- [Deploy Stormpath on Heroku with Express.js](https://github.com/stormpath/stormpath-heroku-express-sample)
 
-## Contributing
 
-In lieu of a formal style guide, take care to maintain the existing coding
-style.  Add unit tests for any new or changed functionality.  Lint and test
-your code using [Grunt](http://gruntjs.com/).
+## Support
 
-You can make your own contributions by forking the develop branch of this
-repository, making your changes, and issuing pull request on the develop branch.
+We're here to help if you get stuck.  There are several ways that you an get in
+touch with a member of our team:
 
-We regularly maintain this repository, and are quick to review pull requests and
-accept changes!
+* Send an email to [support@stormpath.com](mailto:support@stormpath.com)
+* Open a Github Issue on this repository.
+* Join us on our Slack channel: [https://talkstormpath.slack.com](https://talkstormpath.slack.com)
 
-We <333 contributions!
+[Stormpath AngularJS SDK]: https://github.com/stormpath/stormpath-sdk-angularjs
+[Stormpath Product Guide]: https://docs.stormpath.com/rest/product-guide/latest/
+[Stormpath React SDK]: https://github.com/stormpath/stormpath-sdk-react
+[express-stormpath]: https://docs.stormpath.com/nodejs/express/latest/
 
 
 ## Copyright
 
 Copyright &copy; 2015 Stormpath, Inc. and contributors.
 
 This project is open-source via the [Apache 2.0 License](http://www.apache.org/licenses/LICENSE-2.0).
+
+[Client]: https://docs.stormpath.com/nodejs/api/client
+[Express-Stormpath]: https://github.com/stormpath/stormpath-express
+[Stormpath]: https://stormpath.com
+[Stormpath Angular SDK]: https://github.com/stormpath/stormpath-sdk-angularjs
+[Stormpath Node.js SDK Documentation]: https://docs.stormpath.com/nodejs/api/
+[Stormpath React SDK]: https://github.com/stormpath/stormpath-sdk-react

lib/resource/Tenant.js

@@ -30,41 +30,81 @@ function Tenant() {
 
 utils.inherits(Tenant, InstanceResource);
 
+/**
+ * Not documented as this is proxied by client.getAccounts()
+ *
+ * @private
+ */
 Tenant.prototype.getAccounts = function getTenantAccounts(/* [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['options', 'callback'], true);
   return this.dataStore.getResource(this.accounts.href, args.options, require('./Account'), args.callback);
 };
 
+/**
+ * Not documented as this is proxied by client.getTenantGroups()
+ *
+ * @private
+ */
 Tenant.prototype.getGroups = function getTenantGroups(/* [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['options', 'callback'], true);
   return this.dataStore.getResource(this.groups.href, args.options, require('./Group'), args.callback);
 };
 
+/**
+ * Not documented as this is proxied by client.getApplications()
+ *
+ * @private
+ */
 Tenant.prototype.getApplications = function getTenantApplications(/* [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['options', 'callback'], true);
   return this.dataStore.getResource(this.applications.href, args.options, require('./Application'), args.callback);
 };
 
+/**
+ * Not documented as this is proxied by client.getOrganizations()
+ *
+ * @private
+ */
 Tenant.prototype.getOrganizations = function getTenantOrganizations(/* [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['options', 'callback'], true);
   return this.dataStore.getResource(this.organizations.href, args.options, require('./Organization'), args.callback);
 };
 
+/**
+ * Not documented as this is proxied by client.createApplication()
+ *
+ * @private
+ */
 Tenant.prototype.createApplication = function createTenantApplication(/* app, [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['app', 'options', 'callback']);
   this.dataStore.createResource('/applications', args.options, args.app, require('./Application'), args.callback);
 };
 
+/**
+ * Not documented as this is proxied by client.createOrganization()
+ *
+ * @private
+ */
 Tenant.prototype.createOrganization = function createTenantOrganization(/* app, [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['app', 'options', 'callback']);
   this.dataStore.createResource('/organizations', args.options, args.app, require('./Organization'), args.callback);
 };
 
+/**
+ * Not documented as this is proxied by client.getDirectories()
+ *
+ * @private
+ */
 Tenant.prototype.getDirectories = function getTenantDirectories(/* [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['options', 'callback'], true);
   return this.dataStore.getResource(this.directories.href, args.options, require('./Directory'), args.callback);
 };
 
+/**
+ * Not documented as this is proxied by client.createDirectory()
+ *
+ * @private
+ */
 Tenant.prototype.createDirectory = function createTenantDirectory(/* dir, [options,] callback */) {
   var args = utils.resolveArgs(arguments, ['dir', 'options', 'callback']);
 

lib/resource/roadmap.md

@@ -13,3 +13,9 @@
 1.0
 
 drop support for Node.js < 4.4.5, generators on the horizon
+
+implement linting in tests
+
+better collection interfaces
+
+ability to cache account group resources - make it easy to whitelist regions for caching