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.

Example popup

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

// create new SDK instance with it's options
const sdk = new AccountsSDK({
  client_id: '<your_app_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:

   npm login

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

   npm whoami

2. Verify you have publish permissions:

   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:

   npm access list collaborators @livechat/accounts-sdk | grep "$(npm whoami)"

   Or list all collaborators with write permission:

   npm access list collaborators @livechat/accounts-sdk | grep write

3. Create a new branch for the release:

   git checkout -b release-v2.0.11  # use the appropriate version number

4. Update the version in package.json following semantic versioning:

   npm version patch --no-git-tag-version  # for bug fixes (2.0.10 -> 2.0.11)
   npm version minor --no-git-tag-version  # for new features (2.0.10 -> 2.1.0)
   npm version major --no-git-tag-version  # for breaking changes (2.0.10 -> 3.0.0)

5. Update the CHANGELOG.md:

   • Move all items from the [Unreleased] section to a new version section with the release version number and date
   • Ensure the changes are categorized properly (Added, Changed, Fixed, Security, Documentation)
   • Add a new empty [Unreleased] section at the top
   • Update the version comparison links at the bottom of the file

   Example:

   ## [Unreleased]
   
   
   ## [2.0.11] - 2026-02-09
   
   ### Fixed
   - Fix issue with authentication flow

   Then commit both changes:

   git add package.json package-lock.json CHANGELOG.md
   git commit -m "Bump version to 2.0.11"

6. Build the package:

   npm run build

7. Run tests to ensure everything works:

   npm test

8. Push the branch:

   git push origin release-v2.0.11

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

10. After the PR is merged, checkout the default branch and pull the latest changes:

    git checkout master
    git pull

11. Create and push the git tag on the merged commit:

    git tag v2.0.11
    git push origin v2.0.11

12. Publish to npm:

    npm publish

Note: Tagging after the PR is merged keeps the tag on the commit that actually landed on the default branch (important when using squash/rebase merges). The prepare script will automatically run the build before publishing.

Beta Release Process

To release a beta version of the package for testing purposes:

1. Make sure you're logged in to npm:

   npm login
   npm whoami  # confirm you're logged in

2. Create a beta version (without committing):

   npm version prerelease --preid=beta --no-git-tag-version

   This will bump the version to something like 2.1.4-beta.0. For subsequent beta iterations:

   npm version prerelease --no-git-tag-version  # increments to beta.1, beta.2, etc.

3. Build the package:

   npm run build

4. Run tests to ensure everything works:

   npm test

5. Publish to npm with the beta tag:

   npm publish --tag beta

Note: The --tag beta flag ensures that this version is not installed by default. Users must explicitly install it with npm install @livechat/accounts-sdk@beta. You can view all published beta versions with npm view @livechat/accounts-sdk versions.