docs(methods): setup all methods basic reference and examples (#10)

fixes #10

Author: leomp12

README.md

@@ -17,7 +17,7 @@ It's available for both Node.js and browser environments.
 ```js
 import ecomAuth from '@ecomplus/auth'
 
-ecomAuth.login(localStorage.getItem('username'), localStorage.getItem('password'), localStorage.getItem('store_id'))
+ecomAuth.login(localStorage.getItem('username'), localStorage.getItem('password'))
 
 ecomAuth.on('login', self => {
   console.log('Login OK!', self)

src/constructor.js

@@ -73,7 +73,7 @@ const EcomAuth = function (storeId, lang) {
     }
   })
 
-  this.login = (userOrEmail, password) => login(ecomAuth, userOrEmail, password)
+  this.login = (userOrEmail, password, isMd5Hash) => login(ecomAuth, userOrEmail, password, isMd5Hash)
 
   this.createEcomplusSession = () => createEcomplusSession(ecomAuth)
 

src/methods/check-login.js

@@ -1,3 +1,18 @@
+/**
+ * @method
+ * @name EcomAuth#checkLogin
+ * @description Check if admin is logged and access token is not expired.
+ *
+ * @returns {boolean}
+ *
+ * @example
+
+if (ecomAuth.checkLogin()) {
+  console.log('Logged')
+}
+
+ */
+
 export default ({ session }) => {
   return Date.now() < new Date(session.expires).getTime() && Boolean(session.access_token)
 }

src/methods/create-ecomplus-session.js

@@ -1,5 +1,18 @@
 import axios from 'axios'
 
+/**
+ * @method
+ * @name EcomAuth#createEcomplusSession
+ * @description Try set E-Com Plus cross domain session after login.
+ *
+ * @returns {Promise<response|error>}
+ *
+ * @example
+
+ecomAuth.createEcomplusSession().then(() => console.log('User session created'))
+
+ */
+
 export default ({ session, checkLogin }) => {
   if (!checkLogin()) {
     return Promise.reject(new Error('Unauthorized, requires login'))

src/methods/fetch-authentication.js

@@ -1,5 +1,22 @@
 import fetchAndCache from '../lib/fetch-and-cache'
 
+/**
+ * @method
+ * @name EcomAuth#fetchAuthentication
+ * @description Fetch current user authentication object from Store API.
+ *
+ * @param {boolean} [mustSkipSession=false] - Skips previously fetched result (refresh cache)
+ *
+ * @returns {Promise<data|error>}
+ *
+ * @example
+
+ecomAuth.fetchAuthentication().then(authentication => {
+  console.log(authentication._id)
+})
+
+ */
+
 export default (self, mustSkipSession) => {
   const url = `/authentications/${self.session.my_id}.json`
   return fetchAndCache(self, url, mustSkipSession)

src/methods/fetch-store.js

@@ -1,5 +1,22 @@
 import fetchAndCache from '../lib/fetch-and-cache'
 
+/**
+ * @method
+ * @name EcomAuth#fetchStore
+ * @description Fetch current store object from Store API.
+ *
+ * @param {boolean} [mustSkipSession=false] - Skips previously fetched result (refresh cache)
+ *
+ * @returns {Promise<data|error>}
+ *
+ * @example
+
+ecomAuth.fetchStore().then(store => {
+  console.log(store._id)
+})
+
+ */
+
 export default (self, mustSkipSession) => {
   const url = `/stores/${self.session.store_id}.json`
   return fetchAndCache(self, url, mustSkipSession, 'store')

src/methods/get-authentication-id.js

@@ -1,3 +1,16 @@
+/**
+ * @method
+ * @name EcomAuth#getAuthenticationId
+ * @description Returns current session authentication ID.
+ *
+ * @returns {string|null}
+ *
+ * @example
+
+console.log(ecomAuth.getAuthenticationId())
+
+ */
+
 export default ({ session }) => {
   if (session && session.my_id) {
     return session.my_id

src/methods/get-session.js

@@ -1,3 +1,17 @@
+/**
+ * @method
+ * @name EcomAuth#getSession
+ * @description Returns current session object (without token).
+ *
+ * @returns {object}
+ *
+ * @example
+
+const session = ecomAuth.getSession()
+console.log(session.my_id, session.store_id)
+
+ */
+
 export default ({ session }) => {
   return {
     ...session,

src/methods/login.js

@@ -1,7 +1,26 @@
 import { store } from '@ecomplus/client'
 import * as md5 from 'blueimp-md5'
 
-export default (self, userOrEmail, password) => {
+/**
+ * @method
+ * @name EcomAuth#login
+ * @description Try to login and authenticate admin with email or username and password.
+ *
+ * @param {string} userOrEmail - Admin username or email address
+ * @param {string} password - Password or MD5 hash
+ * @param {boolean} [isMd5Hash=false] - If password argument is already the MD5 hash string
+ *
+ * @returns {Promise<self|error>}
+ *
+ * @example
+
+ecomAuth.login('leo', '1234567890').then(() => {
+  console.log(ecomAuth.getSession())
+})
+
+ */
+
+export default (self, userOrEmail, password, isMd5Hash) => {
   const { storeId, setSession } = self
 
   let url = '/_login.json'
@@ -20,7 +39,7 @@ export default (self, userOrEmail, password) => {
     data: {
       email,
       username,
-      pass_md5_hash: md5(password)
+      pass_md5_hash: isMd5Hash === true ? password : md5(password)
     }
   })
 

src/methods/logout.js

@@ -1,5 +1,18 @@
 import emitter from '../lib/emitter'
 
+/**
+ * @method
+ * @name EcomAuth#logout
+ * @description Reset admin session object.
+ *
+ * @returns {self}
+ *
+ * @example
+
+ecomAuth.logout()
+
+ */
+
 export default (self) => {
   self.session.access_token = ''
   emitter.emit('logout', self)