Documentation
Events

Events

The Cede SDK exposes an event emitter. The events allow you to listen to the cache changes, OAuth tokens, and hydration errors.

The Cede SDK exports an enum to retrieve every event used:

export enum CedeSDKEvents {
  CACHE_UPDATE = "cache-update",
  CACHE_DELETE = "cache-delete",
  OAUTH_REVOKED = "oauth-revoked",
  OAUTH_REFRESHED = "oauth-refreshed",
  ERROR = "error",
}

Event Emitter

Cede SDK exposes an event emitter that you can access after instantiation.

import CedeSDK, { CedeSDKEvents } from "@cedelabs-private/sdk";
 
const cedeSDK = new CedeSDK("MOCK");
cedeSDK.eventEmitter.on(CedeSDKEvents.CACHE_UPDATE, (props) => {
  console.log(props);
});
// {
// 	key: 'portfolio-balances-1223-4562-5432-5345',
// 	value: {
// 		BTC: {
// 			...
// 		}
// 	},
// 	ttl: 30000
// }

Cache Events

Cache events are triggered when a cache is updated or deleted. As an integrator, you can use this event to bind SDK's data to your application, even though it's highly recommended to implement your custom cache storage (see Cache for more details).

event: CACHE_UPDATE
handler prototype:

async ({ key, value }: { key: string; value: SDKCacheItem<Any> }) => void

params:

  • key - string
    The cache key.
  • value - SDKCacheItem<Any>
    The cache value, see SDKCacheItem for details.

event: CACHE_DELETE
handler prototype:

async (key: string) => void

params

  • key - string
    The cache key.

OAuth Events

event: OAUTH_REVOKED
handler prototype:

async ({ exchangeInstanceId }: { exchangeInstanceId: string }) => void

params:

  • exchangeInstanceId - string
    The exchange instance identifier.
💡

You could handle this event by notifying your user that the exchange has been disconnected and suggesting they reconnect.

event: OAUTH_REFRESHED
handler prototype:

async ({ exchangeInstanceId, tokens }: { exchangeInstanceId: string; tokens: OAuth2Tokens }) => void

params:

  • exchangeInstanceId - string
    The exchange instance identifier.
  • tokens - OAuth2Tokens
    The new OAuth tokens, see OAuth2Tokens for details.
💡

The Cede SDK automatically refreshes the OAuth tokens when they expire. If OAuth tokens are refreshed, you must use this event to update the expired tokens in your application storage.

Error Events

Error events are triggered when an error occurs while hydrating a cache entry. The hydration system is described below and involves non-awaited promises. This event allows you to catch errors and handle them.

event: ERROR
handler prototype:

async (error: Error) => void

params:

  • error - Error
    The error object.

Example:

import CedeSDK, { CedeSDKEvents } from "@cedelabs-private/sdk";
 
const cedeSDK = new CedeSDK("MOCK");
 
cedeSDK.eventEmitter.on(CedeSDKEvents.ERROR, (error) => {
  console.error(error);
});

Hydration

The Cede SDK exports an enum containing the cache keys used for hydration:

export enum HydrationItem {
  BALANCES = "balances",
}

Hydration is a system that consists of returning the previous result of a query (if available) while simultaneously starting a refresh. it. Once the data has been refreshed, an event is emitted to signal its availability.

Some methods, like getBalances, accept cache management fields as parameters. The optional parameter disableHydration allows you to disable/enable the hydration system for a specific call (default is true).

import CedeSDK, { HydrationItem } from "@cedelabs-private/sdk";
 
...
const balances = await cedeSDK.api.getBalances({ exchangeInstanceId, opts: { disableHydration: true } });
console.log(balances);
// {
//   "binance": {
//     ...
//     "identifier": "portfolio-balances-1223-4562-5432-5345",
//     "value": {
//       "USDT": {
//         "totalBalance": 100,
//         "refTotalBalance": 100,
//         ...
//       }
//     }
//   }
// }
 
/* Perform a trade */
await cedeSDK.api.createOrder({
  pairSymbol: "USDT/USDC",
  orderType: "market",
  orderSide: "sell",
  amount: "10",
  ...
});
 
const balances = await cedeSDK.api.getBalances({ exchangeInstanceId, opts: { disableHydration: false } });
console.log(balances);
// {
//   "binance": {
//     ...
//     "identifier": "portfolio-balances-1223-4562-5432-5345",
//     "value": {
//       "USDT": {
//         "totalBalance": 100,
//         "refTotalBalance": 100,
//       }
//     }
//   }
// }
 
/* Note: It's generally bad practice to not set events handler early in the application lifecycle, but this example
  * illustrates the hydration system uses the reading order chronologically to illustrate the hydration system. */
cedeSDK.eventEmitter.on(HydrationItem.BALANCES, (updatedBalances) => {
  console.log(updatedBalances);
// {
//   "binance": {
//     ...
//     "identifier": "portfolio-balances-1223-4562-5432-5345",
//     "value": {
//       "USDT": {
//         "totalBalance": 90,
//         "refTotalBalance": 90,
//         ...
//       }
//       "USDC": {
//         "totalBalance": 10,
//         "refTotalBalance": 10,
//         ...
//       }
//     }
//   }
// }
});
ChangelogCache