Account client for the browser
hoodie-client-account
is a JavaScript front-end client for
the Account JSON API.
It persists session information in localStorage and provides
front-end friendly APIs for things like creating a user account,
confirming, resetting a password, changing profile information,
or closing the account.
There is also an admin-specific account client
// Account loaded via <script> or require('hoodie-client-account')
var account = new Account('https://example.com/account/api')
if (account.isSignedIn()) {
renderWelcome(account)
}
account.on('signout', redirectToHome)
- Constructor
- account.username
- account.signUp
- account.signIn
- account.signOut
- account.get
- account.fetch
- account.profile.get
- account.profile.fetch
- account.profile.update
- account.on
- account.one
- account.off
- Events
new Account({
// required. Path or full URL to root location of the account JSON API
url: '/api',
// name of localStorage key where to persist the session state.
// Defaults to "_session"
cacheKey: 'myapp.session'
})
Read-only. Returns the username if signed in, otherwise undefined
.
Returns true
if user is currently signed in, otherwise false
.
account.isSignedIn()
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)
Argument | Type | Required |
---|---|---|
accountProperties.username |
String | Yes |
accountProperties.password |
String | Yes |
Resolves with accountProperties
:
{
"id": "account123",
"username": "pat",
"createdAt": "2016-01-01T00:00.000Z",
"updatedAt": "2016-01-01T00:00.000Z"
}
Rejects with:
InvalidError |
Username must be set |
---|---|
SessionError |
Must sign out first |
ConflictError |
Username <username> already exists |
ConnectionError |
Could not connect to server |
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
Creates a user session
account.signIn(options)
Argument | Type | Description | Required |
---|---|---|---|
options.username |
String | - | Yes |
options.password |
String | - | Yes |
Resolves with sessionProperties
:
{
"id": "session123",
"account": {
"id": "account123",
"username": "pat",
"createdAt": "2016-01-01T00:00.000Z",
"updatedAt": "2016-01-02T00:00.000Z",
"profile": {
"fullname": "Dr. Pat Hook"
}
}
}
Rejects with:
UnconfirmedError |
Account has not been confirmed yet |
---|---|
UnauthorizedError |
Invalid Credentials |
Error |
A custom error set on the account object, e.g. the account could be blocked due to missing payments |
ConnectionError |
Could not connect to server |
Example
account.signIn({
username: 'pat',
password: 'secret'
}).then(function (sessionProperties) {
alert('Ohaj, ' + sessionProperties.account.username)
}).catch(function (error) {
alert(error)
})
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:
Error |
A custom error thrown in a before:signout hook |
---|
Example
account.signOut().then(function (sessionProperties) {
alert('Bye, ' + sessionProperties.account.username)
}).catch(function (error) {
alert(error)
})
Returns account properties from local cache.
account.get(properties)
Argument | Type | Description | Required |
---|---|---|---|
properties |
String or Array of strings | When String, only this property gets returned. If array of strings, only passed properties get returned | No |
Returns object with account properties, or undefined
if not signed in.
Examples
var properties = account.get()
alert('You signed up at ' + properties.createdAt)
var createdAt = account.get('createdAt')
alert('You signed up at ' + createdAt)
var properties = account.get(['createdAt', 'updatedAt'])
alert('You signed up at ' + properties.createdAt)
Fetches account properties from server.
account.fetch(properties)
Argument | Type | Description | Required |
---|---|---|---|
properties |
String or Array of strings | When String, only this property gets returned. If array of strings, only passed properties get returned. Property names can have `.` separators to return nested properties. | No |
Resolves with accountProperties
:
{
"id": "account123",
"username": "pat",
"createdAt": "2016-01-01T00:00.000Z",
"updatedAt": "2016-01-02T00:00.000Z"
}
Rejects with:
UnauthenticatedError |
Session is invalid |
---|---|
ConnectionError |
Could not connect to server |
Examples
account.fetch().then(function (properties) {
alert('You signed up at ' + properties.createdAt)
})
account.fetch('createdAt').then(function (createdAt) {
alert('You signed up at ' + createdAt)
})
account.fetch(['createdAt', 'updatedAt']).then(function (properties) {
alert('You signed up at ' + properties.createdAt)
})
account.validate()
🐕 TO BE DONE: #14
account.profile.get()
Returns profile properties from local cache.
account.profile.get(properties)
Argument | Type | Description | Required |
---|---|---|---|
properties |
String or Array of strings | When String, only this property gets returned. If array of strings, only passed properties get returned. Property names can have `.` separators to return nested properties. | No |
Returns object with profile properties, or undefined
if not signed in.
Examples
var properties = account.profile.get()
alert('Hey there ' + properties.fullname)
var fullname = account.profile.get('fullname')
alert('Hey there ' + fullname)
var properties = account.profile.get(['fullname', 'address.city'])
alert('Hey there ' + properties.fullname + '. How is ' + properties.address.city + '?')
Fetches profile properties from server.
account.profile.fetch(options)
Argument | Type | Description | Required |
---|---|---|---|
properties |
String or Array of strings | When String, only this property gets returned. If array of strings, only passed properties get returned. Property names can have `.` separators to return nested properties. | No |
Resolves with profileProperties
:
{
"id": "account123-profile",
"fullname": "Dr Pat Hook",
"address": {
"city": "Berlin",
"street": "Adalberststraße 4a"
}
}
Rejects with:
UnauthenticatedError |
Session is invalid |
---|---|
ConnectionError |
Could not connect to server |
Examples
account.fetch().then(function (properties) {
alert('Hey there ' + properties.fullname)
})
account.fetch('fullname').then(function (createdAt) {
alert('Hey there ' + fullname)
})
account.fetch(['fullname', 'address.city']).then(function (properties) {
alert('Hey there ' + properties.fullname + '. How is ' + properties.address.city + '?')
})
Update profile properties on server and local cache
account.profile.update(changedProperties)
Argument | Type | Description | Required |
---|---|---|---|
changedProperties |
Object | Object of properties & values that changed. Other properties remain unchanged. | No |
Resolves with profileProperties
:
{
"id": "account123-profile",
"fullname": "Dr Pat Hook",
"address": {
"city": "Berlin",
"street": "Adalberststraße 4a"
}
}
Rejects with:
UnauthenticatedError |
Session is invalid |
---|---|
InvalidError |
Custom validation error |
ConnectionError |
Could not connect to server |
Examples
account.profile.update({fullname: 'Prof Pat Hook'}).then(function (properties) {
alert('Congratulations, ' + properties.fullname)
})
account.on(event, handler)
Example
account.on('signin', function (accountProperties) {
alert('Hello there, ' + accountProperties.username)
})
Call function once at given account event.
account.one(event, handler)
Example
account.on('signin', function (accountProperties) {
alert('Hello there, ' + accountProperties.username)
})
Removes event handler that has been added before
account.off(event, handler)
Example
hoodie.off('connectionstatus:disconnected', showNotification)
signup |
New user account created successfully |
---|---|
signin |
Successfully signed in to an account |
signout |
Successfully signed out |
unauthenticate |
Server responded with "unauthenticated" when checking session 🐕 TO BE DONE #35 |
reauthenticate |
Successfully signed in after "unauthenticated" state 🐕 TO BE DONE #35 |
In Node.js
Run all tests and validate JavaScript Code Style using standard
npm test
To run only the tests
npm run test:node
Have a look at the Hoodie project's contribution guidelines. If you want to hang out you can join our Hoodie Community Chat.
Appache 2.0