truevault

TrueVault JavaScript SDK

The official JavaScript SDK for TrueVault. For more information about TrueVault, check out our website and API documentation. To see how the SDK is used in a real application, check out the TrueVault React Sample App. You can also browse the documentation for this SDK.

Note: This SDK is supported on Node JS, AWS Lambda, React Native, and modern browsers (tested in Chrome).

Install using unpkg CDN

Simply copy this line into your HTML:

<script src="https://unpkg.com/truevault@1.3.1/build/index-web.js"></script>

Install using yarn / npm

First download the package using yarn or npm.

yarn add truevault

// OR

npm install truevault

Then import the JS SDK into your project:

ES6

import TrueVaultClient from 'truevault';

ES5

const TrueVaultClient = require('truevault');

Usage

Initialize a TrueVaultClient using an access token or API key:

const tvClient = new TrueVaultClient({apiKey: 'your api key'});

You can also create a new TrueVaultClient by logging in:

const tvClient = await TrueVaultClient.login(accountId, username, password, mfaCode);

See the documentation for more info.

Asynchronous Requests

The methods in this SDK make asynchronous web requests to TrueVault and return Promises. We recommend using async/await in favor of Promises wherever possible for clarity and conciseness.

async/await

async readTrueVaultDocument() {
    try {
        const response = await tvClient.readDocument(vaultId, documentId);
        console.log(response);
    } catch (err) {
        console.error(err);
    }
}

Promises

readTrueVaultDocument() {
    tvClient.readDocument(vaultId, documentId).then(response => {
        console.log(response);
    }).catch(err => {
        console.error(err);
    });
}

Example

Test out the SDK with this simple JSFiddle example.

Development

Make changes to index.js and then bundle them into build/index.js with webpack:

yarn install

yarn build

The integration tests are built with Mocha. To run them, first copy test.env.template to test.env and populate test.env with values from your account. To run tests, do yarn test. You can run a subset of tests via yarn test -g [filter regex]

To run in a browser, first rebuild the test file with webpack: yarn build-browser-tests and then load test/index.html in a browser.

Running in AWS lambda is more complicated:

1. Build a version of the tests for inclusion in lambda: yarn build-lambda-tests
2. Create a new Lambda function. Choose Node 8.10 for the runtime, run-lambda-tests.runTests for the handler, 5 minutes for the timeout, and supply the generated lambda.zip.
3. Perform a test invocation to run the tests. They take a few minutes to run, and no output appears until they complete.

Documentation

This project uses documentationjs. To generate the docs:

rm -rf docs && yarn documentation -- build index.js -f html -o docs

The documentation is available via GitHub Pages.

License

This SDK is released under the BSD 3-Clause License.

Releasing a new version

• Update version in package.json, update the version in README.md.
• Update the changelog in README.md
• Rebuild distribution files; see above
• Rebuild documentation; see above
• Commit
• npm publish
• Tag

CHANGELOG

v1.3.1

• CHANGE: getDocument updated to support v2 of the Document API

v1.3.0

• FEATURE: Add support for managing scoped access tokens

v1.2.1

• BUGFIX: Correct issue that prevented setting schema id or owner id when creating documents
• FEATURE: Add support for configuring access token expiration

v1.1.0

• FEATURE: Get blob methods return the blob's content type and filename, in addition to the blob itself

v1.0.2

• FEATURE: Minify production builds to reduce file size

v1.0.1

• FEATURE: Add JSDoc to blob methods

v1.0.0

• BUGFIX: Fix error in readUserSchema method
• CHANGE: listUsers now defaults to full=false, rather than full=true
• CHANGE: TrueVaultClient constructor no longer accepts a string parameter; authentication information must be provided as an object
• CHANGE: removeUsersFromGroup renamed to removeUsersFromGroupReturnUserIds
• CHANGE: deleteGroup returns the deleted group, rather than the top-level TrueVault API response
• CHANGE: deleteBlob, updateBlobOwner, updateBlob, createBlob, createBlobWithProgress return the blob's info, rather than the top-level TrueVault API response
• CHANGE: getBlob and getBlobWithProgress return an object with a blob property, rather than just the blob
• CHANGE: startUserMfaEnrollment now returns the mfa response object rather than the top-level TrueVault API response
• CHANGE: createVault now returns the vault object rather than the top-level TrueVault API response
• CHANGE: createDocument, updateDocument and updateDocumentOwner now return the document rather than the top-level TrueVault API response
• CHANGE: getFullGroup renamed to readFull group, and it now returns the group rather than the top-level TrueVault API response
• CHANGE: createSchema, createUserSchema, readUserSchema, updateUserSchema and deleteUserSchema now return the schema rather than the top-level TrueVault API response
• CHANGE: searchUsers, searchDocuments, and readUsers now decode attributes
• CHANGE: listPasswordResetFlows returns an array of password reset flows rather than the top-level TrueVault API response
• CHANGE: sendPasswordResetEmail returns undefined rather than the top-level TrueVault API response
• CHANGE: deleteDocument returns an object with the deleted document's info, rather than the top-level TrueVault API response
• FEATURE: Add support AWS Lambda, NodeJS, and React Native
• FEATURE: Allow specifying status when creating user
• FEATURE: Access token and auth header exposed as properties
• FEATURE: Error objects from failed requests include transaction_id
• FEATURE: readCurrentUser now allows setting full=false
• FEATURE: listDocuments now supports specifying full parameter
• FEATURE: Add updateCurrentUser, listUsersWithStatus, removeUsersFromGroup, listVaults, readVault, updateVault, deleteVault, updateSchema, readSchema, listSchema, deleteSchema, listDocumentsInSchema methods