hoodie-account-client

Account client API for the browser

hoodie-account-client is a JavaScript client for the Account JSON API. It persists session information in localStorage (or your own store API) and provides front-end friendly APIs for things like creating a user account, confirming, resetting a password, changing profile information, or closing the account.

Example

// Account loaded via <script> or require('@hoodie/account-client')
var account = new Account('https://example.com/account/api')

// check if user is signed in
account.get('session').then(function (session) {
  if (session) {
    renderDashboard()
  } else {
    renderWelcome()
  }
})

account.on('signout', redirectToHome)

API

• Constructor
• account.validate
• account.signUp
• account.signIn
• account.signOut
• account.destroy
• account.get
• account.update
• account.profile.get
• account.profile.fetch
• account.profile.update
• account.request
• account.on
• account.one
• account.off
• Events
• Hooks
• Requests

Constructor

new Account(options)

Returns account API.

Example

new Account({
  url: '/api',
  id: 'user123',
  cacheKey: 'myapp.session',
  validate: function (options) {
    if (options.username.length < 3) {
      throw new Error('Username must have at least 3 characters')
    }
  }
})

account.validate

Calls the function passed into the Constructor. Returns a Promise that resolves to true by default

account.validate(options)

Resolves with an argument.

Rejects with any errors thrown by the function originally passed into the Constructor.

Example

var account = new Account({
  url: '/api',
  cacheKey: 'app.session',
  validate: function (options) {
    if (options.password.length < 8) {
      throw new Error('password should contain at least 8 characters')
    }
  }
})

account.validate({
  username: 'DocsChicken',
  password: 'secret'
})

.then(function () {
  console.log('Successfully validated!')
})

.catch(function (error) {
  console.log(error) // should be an error about the password being too short
})

account.signUp

Creates a new user account on the Hoodie server. Does not sign in the user automatically, account.signIn must be called separately.

account.signUp(accountProperties)

Resolves with accountProperties:

{
  "id": "account123",
  "username": "pat",
  "createdAt": "2016-01-01T00:00.000Z",
  "updatedAt": "2016-01-01T00:00.000Z"
}

Rejects with:

Example

account.signUp({
  username: 'pat',
  password: 'secret'
}).then(function (accountProperties) {
  alert('Account created for ' + accountProperties.username)
}).catch(function (error) {
  alert(error)
})

🐕 Implement account.signUp with profile: {...} option: #11

account.signIn

Creates a user session

account.signIn(options)

Resolves with accountProperties:

{
  "id": "account123",
  "username": "pat",
  "createdAt": "2016-01-01T00:00.000Z",
  "updatedAt": "2016-01-02T00:00.000Z",
  "profile": {
    "fullname": "Dr. Pat Hook"
  }
}

Rejects with:

Example

account.signIn({
  username: 'pat',
  password: 'secret'
}).then(function (sessionProperties) {
  alert('Ohaj, ' + sessionProperties.account.username)
}).catch(function (error) {
  alert(error)
})

account.signOut

Deletes the user’s session

account.signOut()

Resolves with sessionProperties like account.signin, but without the session id:

{
  "account": {
    "id": "account123",
    "username": "pat",
    "createdAt": "2016-01-01T00:00.000Z",
    "updatedAt": "2016-01-02T00:00.000Z",
    "profile": {
      "fullname": "Dr. Pat Hook"
    }
  }
}

Rejects with:

Example

account.signOut().then(function (sessionProperties) {
  alert('Bye, ' + sessionProperties.account.username)
}).catch(function (error) {
  alert(error)
})

account.destroy

Destroys the account of the currently signed in user.

account.destroy()

Resolves with sessionProperties like account.signin, but without the session id:

{
  "account": {
    "id": "account123",
    "username": "pat",
    "createdAt": "2016-01-01T00:00.000Z",
    "updatedAt": "2016-01-02T00:00.000Z",
    "profile": {
      "fullname": "Dr. Pat Hook"
    }
  }
}

Rejects with:

Example

account.destroy().then(function (sessionProperties) {
  alert('Bye, ' + sessionProperties.account.username)
}).catch(function (error) {
  alert(error)
})

account.get

Returns account properties from local cache or fetches them from remote. Fetches properties from remote unless

1. User is signed out
2. Only id and or session properties are requested
3. options.local is set to true

account.get(properties, options)

Resolves with object with account properties or value of passed path, depending on the properties argument passed

Examples

account.get().then(function (properties) {
  alert('You signed up at ' + properties.createdAt)
})
account.get('createdAt').then(function (createdAt) {
  alert('You signed up at ' + createdAt)
})
account.get(['username', 'createdAt']).then(function (properties) {
  alert('Hello ' + properties.username + '! You signed up at ' + properties.createdAt)
})
account.get({local: true}).then(function (cachedProperties) {
  // ...
})
account.get('session').then(function (session) {
  if (session) {
    // user is signed in
  } else {
    // user is signed out
  }
})
account.get('session.invalid').then(function (hasInvalidSession) {
  if (hasInvalidSession) {
    // user is signed in but has an expired or otherwise invalidated session
  }
})

account.update

Update account properties on server and local cache

account.update(changedProperties)

Resolves with accountProperties:

{
  "id": "account123",
  "username": "pat",
  "createdAt": "2016-01-01T00:00.000Z",
  "updatedAt": "2016-01-01T00:00.000Z"
}

Rejects with:

Example

account.update({username: 'treetrunks'}).then(function (properties) {
  alert('You are now known as ' + properties.username)
})

account.profile.get

Returns account properties from local cache or fetches them from remote.

account.profile.get(properties)

Resolves with profile properties, falls back to empty object {}. If a single string is passed as properties then resolves with value for that property.

Examples

account.profile.get().then(function (properties) {
  alert('Hey there ' + properties.fullname)
})
account.profile.get('fullname').then(function (fullname) {
  alert('Hey there ' + fullname)
})
account.profile.get(['fullname', 'address.city'], {local: true}).then(function (properties) {
  alert('Hey there ' + properties.fullname + '. How is ' + properties.address.city + '?')
})

account.profile.update

Update profile properties on server and local cache

account.profile.update(changedProperties)

Resolves with profileProperties:

{
  "id": "account123-profile",
  "fullname": "Dr Pat Hook",
  "address": {
    "city": "Berlin",
    "street": "Adalberststraße 4a"
  }
}

Rejects with:

Example

account.profile.update({fullname: 'Prof Pat Hook'}).then(function (properties) {
  alert('Congratulations, ' + properties.fullname)
})

account.request

Sends a custom request to the server, for things like password resets, account upgrades, etc.

account.request(properties)

Resolves with requestProperties:

{
  "id": "request123",
  "type": "passwordreset",
  "contact": "[email protected]",
  "createdAt": "2016-01-01T00:00.000Z",
  "updatedAt": "2016-01-01T00:00.000Z"
}

Rejects with:

Example

account.request({type: 'passwordreset', contact: '[email protected]'}).then(function (properties) {
  alert('A password reset link was sent to ' + properties.contact)
})

account.on

account.on(event, handler)

Example

account.on('signin', function (accountProperties) {
  alert('Hello there, ' + accountProperties.username)
})

account.one

Call function once at given account event.

account.one(event, handler)

Example

account.one('signin', function (accountProperties) {
  alert('Hello there, ' + accountProperties.username)
})

account.off

Removes event handler that has been added before

account.off(event, handler)

Example

account.off('singin', showNotification)

Events

Hooks

// clear user’s local store signin and after signout
account.hook.before('signin', function (options) {
  return localUserStore.clear()
})
account.hook.after('signout', function (options) {
  return localUserStore.clear()
})

See before-after-hook for more information.

Requests

Hoodie comes with a list of built-in account requests, which can be disabled, overwritten or extended in hoodie-account-server

When a request succeeds, an event with the same name as the request type gets emitted. For example, account.request({type: 'passwordreset', contact: '[email protected]') triggers a passwordreset event, with the requestProperties passed as argument.

Testing

Local setup

git clone https://github.com/hoodiehq/hoodie-account-client.git
cd hoodie-account-client
npm install

In Node.js

Run all tests and validate JavaScript Code Style using standard

npm test

To run only the tests

npm run test:node

To test hoodie-account-client in a browser you can link it into hoodie-account, which provides a dev-server:

git clone https://github.com/hoodiehq/hoodie-account.git
cd hoodie-account
npm install
npm link /path/to/hoodie-account-client
npm start

hoodie-account bundles hoodie-account-client on npm start, so you need to restart hoodie-account to see your changes.

Contributing

Have a look at the Hoodie project's contribution guidelines. If you want to hang out you can join our Hoodie Community Chat.

License

Apache 2.0