hoodie-client-account

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

Example

// 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

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'
})

account.username

Read-only. Returns the username if signed in, otherwise undefined.

account.isSignedIn

Returns true if user is currently signed in, otherwise false.

account.isSignedIn()

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)

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

account.signIn

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)
})

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:

`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)
})

account.get

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)

account.fetch

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

account.validate()

🐕 TO BE DONE: #14

account.profile.get

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 + '?')

account.profile.fetch

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 + '?')
})

account.profile.update

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

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.on('signin', function (accountProperties) {
  alert('Hello there, ' + accountProperties.username)
})

account.off

Removes event handler that has been added before

account.off(event, handler)

Example

hoodie.off('connectionstatus:disconnected', showNotification)

events

`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

Testing

In Node.js

Run all tests and validate JavaScript Code Style using standard

npm test

To run only the tests

npm run test:node

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

Appache 2.0

mikehedman / hoodie-client-account Goto Github PK