accountsSDK

accountsSDK is a small library that installs the "Sign in with LiveChat" button on any website or app. It also wraps OAuth flow in an easy-to-use API.

Installation

``
npm install --save @livechat/accounts-sdk
`

Button

Example sign in with LiveChat button designs. Assets are available here.

!Button
!Small button

Example popup

`
import AccountsSDK from '@livechat/accounts-sdk';

// create new SDK instance with it's options
const sdk = new AccountsSDK({
client_id: ''
});

document.getElementById('login-button').onclick = (e) => {
if (e && e.preventDefault) {
e.preventDefault();
}

sdk.popup().authorize().then((authorizeData)=>{
const transaction = sdk.verify(authorizeData);
if (transaction != null) {
// authorization success
// authorizeData contains accessToken or code
// transation contains state and optional code_verifier (code + PKCE)
}
}).catch((e)=>{

})
};
`

Flows

Authorize using a popup. It's possible to pass options to override constructor options.

`
const sdk = new AccountsSDK(options)
const promise = sdk.popup(options).authorize()
`

Authorize using iframe. It's possible to pass options to override constructor options. Works when a browser doesn't check for ITP, and user authentication is set.

`
const sdk = new AccountsSDK(options)
const promise = sdk.iframe(options).authorize()
`

Authorize using a full redirect. Authorize function performs full browser redirect to an authorization server. authorizeData function checks if authorization is set in URL.

`
const sdk = new AccountsSDK(options)

sdk.redirect().authorizeData().then((authorizeData)=>{
// authorize data found in URL
const transaction = sdk.verify(authorizeData);

}).catch((e)=>{
// authorize data missing, redirect to authorization server
sdk.redirect().authorize()
})
`

Options

- client_id string required registered client ID
- organization_id string organization ID
- prompt string use consent to force consent prompt in a popup and redirect flows
- response_type='token' string OAuth response type, use token or code
- popup_flow='auto' string auto - don't show popup when credentials are not required, manual - always show popup
- state string OAuth state param, auto generated by SDK when empty
- verify_state=true bool a function that returns transaction should verify if the state matches
- scope string - custom scope list, must be a subset of preconfigured client ID scopes
- redirect_uri string OAuth redirect URI - current location by default
- email_hint string fill in an email hint in forms
- server_url='https://accounts.livechat.com' string authorization server url
- path='' string option to provide a path when loading accounts, for example /signup
- tracking object tracking querystring params
- transaction.namespace='com.livechat.accounts' string transaction keys prefix
- transaction.key_length=32 number transaction random state length
- transaction.force_local_storage=false bool try to use local storage instead of cookies
- pkce.enabled=true bool Oauth 2.1 PKCE extension enabled for code grant
- pkce.code_verifier string override auto generated code verifier
- pkce.code_verifier_length=128 number code verifier length, between 43 and 128 characters https://tools.ietf.org/html/rfc7636#section-4.1
- pkce.code_challange_method='S256' string code challange method, use S256 or plain

SJCL

One of components uses crypto library called SJCL. We include a custom build in src/vendor/sjcl.js that only includes the pieces we need and avoids bundler errors caused by Node requires in standard version.

To do this build yourself and verify code integrity, do the following:

1. Clone the SJCL repo.
2. Check out a 1.0.8 version.
3. Run ./configure --without-all --with-sha256 --compress=none to configure our build.
4. Run make sjcl.js to build the file.
5. Compare newly created sjcl.js with the one included in src/vendor.

Release

To release a new version of the package to npm:

1. Make sure you're logged in:
`bash
npm login
`

This will prompt you for your npm username, password, and 2FA code (if enabled).
You can confirm you're logged in with:

`bash
npm whoami
`

2. Verify you have publish permissions:
`bash
npm publish --dry-run
`
This will simulate publishing without actually publishing. If you don't have permission, you'll see:
`
403 Forbidden - You do not have permission to publish to this organization
`

You can also check your permissions with:
`bash
npm access list collaborators @livechat/accounts-sdk | grep "$(npm whoami)"
`

Or list all collaborators with write permission:
`bash
npm access list collaborators @livechat/accounts-sdk | grep write
`

3. Create a new branch for the release:
`bash
git checkout -b release-v2.0.11 # use the appropriate version number
`

4. Update the version in package.json following semantic versioning:
`bash
npm version patch # for bug fixes (2.0.10 -> 2.0.11)
npm version minor # for new features (2.0.10 -> 2.1.0)
npm version major # for breaking changes (2.0.10 -> 3.0.0)
`
This command updates package.json, creates a commit, and creates a git tag locally.

5. Build the package:
`bash
npm run build
`

6. Run tests to ensure everything works:
`bash
npm test
`

7. Push the branch with the tag:
`bash
git push origin release-v2.0.11 --follow-tags
`

8. Create a pull request with the version update and get it reviewed and merged.

9. After the PR is merged, checkout the main branch and pull the latest changes:
`bash
git checkout master
git pull origin master
`

10. Publish to npm:
`bash
npm publish
`

Note: The git tag created by npm version will be included when the PR is merged. Make sure you have the necessary permissions to publish to the @livechat organization on npm. The prepare` script will automatically run the build before publishing.