Docs v1.

README.md

-###### DRAFT ....
+# Zimbra Admin Api Javascript
 
-## Como se usa
+## Table of Contents
+- [Example](https://github.com/ZBoxApp/zimbra-admin-api-js#example)
+- [Install](https://github.com/ZBoxApp/zimbra-admin-api-js#install)
+- [Callback](https://github.com/ZBoxApp/zimbra-admin-api-js#callback)
+- [Errors](https://github.com/ZBoxApp/zimbra-admin-api-js#callback)
+- [Zimbra Resources](https://github.com/ZBoxApp/zimbra-admin-api-js#zimbra-resources)
+- [Common Functions](https://github.com/ZBoxApp/zimbra-admin-api-js#common-functions)
+- [Creating Resources](https://github.com/ZBoxApp/zimbra-admin-api-js#creating-resources)
+
+
+## Example
 
 First, instantiate the wrapper.
 ```javascript
@@ -9,30 +19,164 @@ var zimbraApi = new ZimbraAdminApi({
   'user': 'admin@zboxapp.dev',
   'password':'12345678'
 });
+
+var callback = function(err, data) {
+  if (err) return console.log(err);
+  console.log(data);
+};
+
+zimbraApi.getAllDomains(callback);
 ```
 
-Here you see how to get basic information using a function like `getAllDomains`:
+## Install
+**TODO**
+
+## Callback
+You have to pass a `callback` to all the functions, that receives to params:
+
+1. `error`, if any
+2. `data`, if any
+
+For this documentations `callback` will always be:
 
 ```javascript
-zimbraApi.getAllDomains(function(err, data){
+function(err, data) {
   if (err) return console.log(err);
-  data.forEach(function(v){
-    console.log(v.id + ' ' + v.name);
-  })
-});
+  console.log(data);
+};
 ```
 
-Here you see how to get basic information using a function like `getAllAccounts`:
+## Errors
+If Zimbra returns an Error, the library returns an `Error` Object with the Zimbra Error
+information. For example, if you look for a non existing `Domain`:
 
 ```javascript
-zimbraApi.getAllAccounts(function(err, data){
-  if (err) return console.log(err);
-  data.forEach(function(v){
-    console.log(v.id + ' ' + v.name);
-  })
-});
+api.getDomain('example.com', callback);
+
+// Error: {status: 500, title: "Internal Server Error", extra: Object}
+// Error.extra: {
+//   code: "account.NO_SUCH_DOMAIN",
+//   reason: "no such domain: example.com"
+// }
+```
+
+## Zimbra Resources
+Zimbra Resources are the things you can manage, like:
+
+* `Accounts`, the email users,
+* `Domains`,
+* `Distribution Lists`,
+* `CoS`, Class of services
+* `Servers`, Zimbra servers
+
+
+## Common Functions
+This are similar functions that you can call for all the `Resources`, so we grouped here
+for brevity:
+
+### Get a Resource
+You can use the resource `name` or `zimbraId`:
+
+```javascript
+zimbraApi.getAccount('account@domain.com', callback);
+// Account {name: "admin@domain.com", id: "eda93f93-ba26-4344-8ae0-1d03964b612a", attrs: Object}
+
+zimbraApi.getAccount('eda93f93-ba26-4344-8ae0-1d03964b612a', callback);
+// Account {name: "admin@domain.com", id: "eda93f93-ba26-4344-8ae0-1d03964b612a", attrs: Object}
+
+
+zimbraApi.getDomain('domain.com', callback);
+// Domain {name: "domain.com", id: "cc0fd82b-7833-4de2-8954-88eb97fb81e9", attrs: Object}
+
+zimbraApi.getDistributionList('list@domain.com', callback);
+// DistributionList {name: "list@domain.com", id: "747972ab-a410-4f17-8d5e-db7be21d75e9", attrs: Object, members: Array[4]}
 ```
 
-## TODOS:
+A successful response will always return a `Object` named after the `Resource` your are requesting.
+
+
+### Get All and Search
+You have the following functions:
+
+* `getAllAccounts(callback, query_object)`,
+* `getAllDomains(callback, query_object)`,
+* `getAllDistributionLists(callback, query_object)`,
+
+`query_object` is an **optional** `Object` that accept the following attributes:
+
+* `query`: An LDAP query or null for everything,
+* `maxResults`: Maximum results that the backend will attempt to fetch from the directory before
+returning an `account.TOO_MANY_SEARCH_RESULTS` error.,
+* `limit`: the maximum number of accounts to return ,
+* `offset`: The starting offset (0, 25, etc),
+* `domain`: The domain name to limit the search to,
+* `sortBy`: Name of attribute to sort on. Default is the account name.,
+* `sortAscending`: Whether to sort in ascending order. Default is 1 (true)
+* `countOnly`: Whether response should be count only. Default is 0 (false),
+* `attrs`: Comma separated list of attributes to ask for
+
+#### Examples
+
+##### 1. Get All Accounts without a query_object
+
+```javascript
+zimbraApi.getAllAccounts(callback);
+// Object {total: 261, more: false, account: Array[261]}
+```
+
+The **Result Object** has the following information:
+
+* `total`: The total quantity of resources that you _request_ can return,
+* `account`, An array with all the `Accounts` objects,
+* `more`: `true` if there are more results that.
+
+##### 2. Get All Accounts with limit and offset
+This is useful if you are doing pagination.
+
+```javascript
+var query_object = { limit: 10, offset: 2 }
+zimbraApi.getAllAccounts(callback);
+// Object {total: 261, more: true, account: Array[10]}
+```
+
+##### 3. Get All DistributionList for the `example.com` Domain
+
+```javascript
+var query_object = { domain: 'example.com' }
+zimbraApi.getAllDistributionLists(callback, query_object);
+// Object {total: 6, more: false, dl: Array[6]}
+```
+
+##### 4. Get All Accounts with an email containing 'basic'
+
+```javascript
+var query_object = { query: 'mail=*basic*' }
+zimbraApi.getAllAccounts(callback, query_object);
+// Object {total: 29, more: false, account: Array[29]}
+```
+
+## Creating Resources
+The methods are:
+
+* `createAccount('email_address', password, zimbra_attributes, callback)`,
+* `createDomain('domain_name', zimbra_attributes, callback)`,
+* `createDistributionList('email_address', zimbra_attributes, callback)`
+
+`zimbra_attributes` must be an `Object`, that can be empty, that should have valid Zimbra attributes
+for the `Resource` being created. For example, lets create an `Account` with:
+
+* First Name (`givenName`),
+* Last Name (`sn`), and
+* A Mail Quota of `50GB` (`zimbraMailQuota`)
+
+```javascript
+var zimbra_attributes = {
+  givenName: 'John',
+  sn: 'Smith',
+  zimbraMailQuota: 53687091200
+}
+zimbraApi.createAccount('user@example.com', 'SuP3rS3cur3P4ss', zimbra_attributes, callback);
+// Account {name: "user@customer.dev", id: "1919c856-08cc-43c9-b927-0c4cf88f50c7", attrs: Object}
+```
 
-Muchas, pero ya viene.
+All the functions returns the created resource `Object`.

lib/zimbra-admin-api.js

@@ -302,8 +302,10 @@ return /******/ (function(modules) { // webpackBootstrap
 	    }
 	
 	    // attributes debe ser un arreglo de objetos:
-	    // resource_data.a = attributes
-	    // attributes = [ { n: 'NOMBRE_DEL_CAMPO_ZIMBRA', '_content': 'VALOR_DEL_CAMPO' } ]
+	    // let resource_attributes = {
+	    //   zimbraSkinLogoURL: 'http://www.zboxapp.com',
+	    //   postOfficeBox: 'ZBoxApp'
+	    // };
 	
 	  }, {
 	    key: 'createAccount',

src/index.js

@@ -203,8 +203,10 @@ export default class ZimbraAdminApi {
   }
 
   // attributes debe ser un arreglo de objetos:
-  // resource_data.a = attributes
-  // attributes = [ { n: 'NOMBRE_DEL_CAMPO_ZIMBRA', '_content': 'VALOR_DEL_CAMPO' } ]
+  // let resource_attributes = {
+  //   zimbraSkinLogoURL: 'http://www.zboxapp.com',
+  //   postOfficeBox: 'ZBoxApp'
+  // };
   createAccount(name, password, attributes, callback) {
     let resource_data = {
       name: { '_content': name },