Documentation
Events

Events

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

The Cede SDK export 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 instanciation.

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 if 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 suggest to reconnect again.

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 ones in your application storage.

Error Events

Error events are triggered when an error occurs while hydrating a cache entry. The hydration system is described bellow and implies 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 to retrieve every cache keys used for hydration:

export enum HydrationItem {
  BALANCES = "balances",
}

Hydration is a system that consists of returning the previous result (if available) of a query while starting to refresh it. Once the data has been refreshed, an event is launched 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 a bad practice to not set events handler as soon as possible, but this example
  * illustrates the hydration system using the reading order as a chronology. */
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,
//         ...
//       }
//     }
//   }
// }
});
TokensCache