liquid-tap v0.3.6
LiquidTap Javascript Client
To manage API tokens, refer to: https://app.liquid.com/settings/api-tokens
To learn more about Liquid Api token management, see the help links below: https://help.liquid.com/connect-to-liquid-via-api
Links
Events Authentication Troubleshooting Contributing
Quick Start
Install via npm or yarn:
npm install liquid-tap
yarn add liquid-tap
OR Include the library:
<script src="../dist/liquid-tap.js"></script>
import { TapClient } from "liquid-tap";
const tap = new TapClient();
const public_channel = tap.subscribe("product_cash_btcsgd_7");
public_channel.bind("updated", function(data) {
console.log("product_cash_btcsgd_7 has been updated", data);
});
Events
Event | Payload | Description |
---|---|---|
connected | { reconnect: boolean } | Fires on successful connection. Contains a boolean indicating whether this was an automatic reconnection. |
disconnected | n/a | Fires on disconnect. |
unavailable | n/a | Fires when a connection is unavailable for any reason. |
tick_received | { event: string, data: any, channel?: string } | Fires on every websocket event. Contains the entire websocket payload. |
authenticated | n/a | Fires when the websocket has successfully authenticated |
authentication_failed | { message: string, attempts: number } | Fires when authentication has failed. Contains a message from the server and the number of authentication attempts. |
authentication_aborted | { attempts: number } | Fires when the maximum number of automatic authentication retries is reached. Contains the number of attempts. |
Binding to events
Callbacks
import { TapClient }, { CLIENT_EVENTS } from 'liquid-js'
var tap = new TapClient();
tap.bind(CLIENT_EVENTS.CONNECTED, function () {
console.log('Connected!');
});
tap.bind(CLIENT_EVENTS.AUTH_SUCCESS, function () {
console.log('Authenticated!');
});
tap.bind(CLIENT_EVENTS.AUTH_FAILURE, function () {
console.log('Authentication Failed!');
});
Promises
var tap = new TapClient();
tap.bind(CLIENT_EVENTS.CONNECTED).then(() => {
console.log("Connected!");
});
tap.bind(CLIENT_EVENTS.AUTH_SUCCESS).then(() => {
console.log("Authenticated!");
});
tap.bind(CLIENT_EVENTS.AUTH_FAILURE).then(() => {
console.log("Authentication Failed!");
});
Options
Key | Type | Default | Description |
---|---|---|---|
wsHost | string | 'tap.liquid.com' | Tap WS host to connect to. |
wsPort | number | 433 | Port to connect to. |
wssPort | number | 433 | SSL Port to connect to. |
useTls | boolean | true | Should connect using SSL. |
auth | AuthType (see below) | null | Authentication information. See below. |
appId | string | 'LiquidTapClient' | Arbitrary name to use in the WS url. |
authenticationTimeout | number (ms) | 5000 | Timeout to assume authentication has failed. (Note a auth_failed event is expected) |
authRetryDelay | number (ms) | 200 | Time to wait before retrying authentication. |
authRetryMaxAttempts | number | 3 | Maximum number of authentication retries. |
Authentication
To subscribe to protected channels, the client must provide a token_id and token_secret which has permission to view those channels. The library will attempt to authenticate three times by default.
Authenticate Sequence
Before Initialization
var tap = new TapClient({
auth: { tokenId: token_id, toeknSecret: token_secret }
});
// Refer to profile page for user_id: https://app.liquid.com/settings/profile
var protected_channel = tap.subscribe("user_<user_id>");
protected_channel.bind("updated", function(data) {
console.log("sensitive user data has been updated", data);
});
After Initialization
The library allows the LiquidTap client to be created and subscribe to public channels, then when a protected channel is required the client can authenticate.
var tap = new TapClient();
var public_channel = tap.subscribe("product_cash_btcsgd_7");
public_channel.bind("updated", function(data) {
console.log("product_cash_btcsgd_7 has been updated", data);
});
tap.authenticate({ tokenId: token_id, tokenSecret: token_secret });
var protected_channel = tap.subscribe("user_<user_id>");
protected_channel.bind("updated", function(data) {
console.log("sensitive user data has been updated", data);
});
Authentication Input
The authentication can be done either by providing an API token ID and secret, JWT token, or callback.
Token ID and Secret
var tap = new TapClient({
auth: { tokenId: token_id, tokenSecret: token_secret }
});
var tap = new TapClient();
tap.authenticate({ tokenId: token_id, tokenSecret: token_secret });
Signed JWT
var tap = new TapClient({ auth: signed_jwt });
var tap = new TapClient();
tap.authenticate(signed_jwt);
Callback (return string)
var tap = new TapClient({
auth: ({ path }) => jwt.encode({token_id: my_token_id, path: path}, my_secret)
});
Callback (return Promise)
The authentication process inside TapClient will wait for the promise to resolve before authenticating.
const createJwtWhenReady = ({ path }) => {
return new Promise<string>(
(resolve) => {
setTimeout(
() => resolve(jwt.encode({token_id: my_token_id, path: path}, my_secret)),
some_wait_period
)
})
}
var tap = new TapClient({
auth: createJwtWhenReady
});
TapClient will also wrap the promise to allow process order management
var tap = new TapClient();
const createJwtWhenReady = ({ path }) => {
return new Promise<string>(
(resolve) => {
setTimeout(
() => resolve(jwt.encode({token_id: my_token_id, path: path}, my_secret)),
some_wait_period
)
})
}
tap.authenticate({
auth: createJwtWhenReady
})
.then(() => {
// do something
})
.catch(() => {
// some error in either generating the jwt, or the websocket request event
})
Callback (which takes another callback)
var tap = new TapClient();
// Create a service to manage nonce and JWT creation
const createJwtWhenReady = ({ path }, callback) => {
setTimeout(
() => {
nonce_counter += 1;
// this callback will return a Promise that resolves when the auth request comes back, either success or failure
await callback(jwt.encode({token_id: my_token_id, path: path, nonce: nonce_counter }, my_secret));
}, some_wait_period
)
}
tap.authenticate({
auth: createJwtWhenReady
})
.then(() => {
// will be called after the resolver for the above JWT creator
})
.catch(() => {
// log error
})
Troubleshooting
Open the chrome dev tools and inspect the network traffic as shown in the image below:
Contributing
Setup
npm install
Development
npm run build:dev
npm run sample
Testing
npm test
Ensure changes are also thoroughly tested with the real world server responses.
Building
npm run build
Ensure to commit compiled assets in dist
.
2 years ago
4 years ago
4 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago
5 years ago