Manager App

Package name: @cypherock/sdk-app-manager

This package allows you to invoke all the device dependent operations.

1. Usage

Install packages: npm i @cypherock/sdk-app-manager @cypherock/sdk-hw-webusb

// NOTE: you can also use `@cypherock/sdk-hw-hid` dependending on the environment
import { DeviceConnection } from '@cypherock/sdk-hw-webusb';
import { ManagerApp } from '@cypherock/sdk-app-manager';

const connection = await DeviceConnection.create();
const managerApp = await ManagerApp.create(connection);

2. Static Methods

2.1. async ManagerApp.create()

Creates an instance of ManagerApp.

Arguments: None

Result: Promise<ManagerApp>

Example:

const managerApp = await ManagerApp.create();

2.2. async ManagerApp.getLatestFirmware(params?)

Fetches the latest firmware of the device from the server.

Arguments:
params? (Optional): GetLatestFirmwareOptions

interface GetLatestFirmwareOptions {
  // If true, downloads the firmware binary
  doDownload?: boolean;
}

Result:Promise<LatestFirmware>

interface LatestFirmware {
  // Latest version
  version: string;

  // Latest firmware binary
  firmware?: Uint8Array;
}

Example:

const { firmware, version } = await ManagerApp.getLatestFirmware({
  doDownload: true,
});

3. Methods

3.1. async managerApp.getDeviceInfo()

Fetches the connected device information.

Arguments: None

Result: Promise<IGetDeviceInfoResultResponse>

interface IGetDeviceInfoResultResponse {
  deviceSerial: Uint8Array;
  firmwareVersion: IVersion | undefined;
  isAuthenticated: boolean;
  appletList: ISupportedAppletItem[];
  isInitial: boolean;
  onboardingStep: OnboardingStep;
}

Example:

const deviceInfo = await managerApp.getDeviceInfo();

console.log(deviceInfo.firmwareVersion);

3.2. async managerApp.getWallets()

Fetches all the wallets present on the connected device.

Arguments: None

Result: Promise<IGetWalletsResultResponse>

interface IGetWalletsResultResponse {
  walletList: IWalletItem[];
}

interface IWalletItem {
  id: Uint8Array;
  name: string;
  hasPin: boolean;
  hasPassphrase: boolean;
  /**
   * This field determines whether the particular wallet is in usable state
   * It does not indicate why the wallet is not usable.
   */
  isValid: boolean;
}

Example:

const { walletList } = await managerApp.getWallets();

const walletNames = walletList.map(wallet => wallet.name);

console.log(walletNames.join(','));

3.3. async managerApp.selectWallet()

Asks the user to select a wallet on the device.

Arguments: None

Result: Promise<ISelectWalletResultResponse>

interface ISelectWalletResultResponse {
  wallet: IWalletItem | undefined;
}

interface IWalletItem {
  id: Uint8Array;
  name: string;
  hasPin: boolean;
  hasPassphrase: boolean;
  /**
   * This field determines whether the particular wallet is in usable state
   * It does not indicate why the wallet is not usable.
   */
  isValid: boolean;
}

Example:

const { wallet } = await managerApp.selectWallet();

console.log(wallet.name);

3.4. async managerApp.destroy()

Destroys the manager instance and the connection to the device.

Arguments: None

Result: Promise<void>

Example:

await managerApp.destroy();

3.5. async managerApp.abort()

Abort any existing operation running on the connected device.

NOTE: This can only abort operations which are triggered by the SDK.

Arguments: None

Result: Promise<void>

Example:

await managerApp.abort();

4. Methods you won't need in most cases

4.1. managerApp.getSDKVersion()

Fetches the SDK Protocol version currently in use with the connected device.

NOTE: You won't need this in most cases.

Arguments: None

Result: boolean

Example:

const sdkVersion = managerApp.getSDKVersion();

4.2. managerApp.isSupported()

Returns if the SDK protocol version is supported with the connected device.

NOTE: You won't need this in most cases. The compatibility check is done automatically on each function call.

Arguments: None

Result: boolean

Example:

const isSupported = managerApp.isSupported();

4.3. async managerApp.authDevice(params?)

Authenticates the device from Cypherock Server to check if it's genuine. Throws error if the device is not genuine.

Arguments:
params? (Optional): IAuthDeviceParams

type AuthDeviceEventHandler = (event: AuthDeviceStatus) => void;

interface IAuthDeviceParams {
  onEvent?: AuthDeviceEventHandler;
  // Email address of the user. If provided, the user will receive an email
  // containing the authentication result
  email?: string;
  cysyncVersion?: string;
}

Result: Promise<void>

Example:

await managerApp.authDevice({ email: '[email protected]' });

4.4. async managerApp.authCard(params?)

Authenticates an X1 card from Cypherock Server to check if it's genuine. Throws error if the card is not genuine.

Arguments:
params? (Optional): IAuthCardParams

type AuthCardEventHandler = (event: AuthCardStatus) => void;

interface IAuthCardParams {
  // The card number to authenticate
  cardNumber?: number;
  isPairRequired?: boolean;
  onEvent?: AuthCardEventHandler;
  // Email address of the user. If provided, the user will receive an email
  // containing the authentication result
  email?: string;
  cysyncVersion?: string;
  onlyFailure?: boolean;
  sessionId?: string;
}

Result: Promise<{ sessionId?: string }>

Example:

await managerApp.authCard({ email: '[email protected]' });

4.5. async managerApp.getLogs(onEvent?)

Fetches the device logs from the connected device.

Arguments:
onEvent? (Optional): GetLogsEventHandler

type GetLogsEventHandler = (event: GetLogsStatus) => void;

Result: Promise<string>

Example:

const logs = await managerApp.getLogs();

console.log(logs);

4.6. async managerApp.trainJoystick(onEvent?)

Trains the user to use joystick on device. On CySync it's used during the onboarding process.

NOTE: You won't need this in most cases.

Arguments:
onEvent? (Optional): TrainJoystickEventHandler

type TrainJoystickEventHandler = (event: TrainJoystickStatus) => void;

Result: Promise<void>

Example:

await managerApp.trainJoystick();

4.7. async managerApp.trainCard(params)

Trains the user to tap card on device. On CySync it's used during the onboarding process.

NOTE: You won't need this in most cases.

Arguments:
params: ITrainCardParams

type TrainCardEventHandler = (event: TrainCardStatus) => void;

interface ITrainCardParams {
  // Callback should return true if the provided wallets were created by the user
  onWallets: (params: ITrainCardResult) => Promise<boolean>;
  onEvent?: TrainCardEventHandler;
}

Result: Promise<ITrainCardResult>

interface ITrainCardResult {
  walletList: IExistingWalletItem[];
  cardPaired: boolean;
}

interface IExistingWalletItem {
  id: Uint8Array;
  name: string;
}

Example:

await managerApp.trainCard({ onWallets: () => Promise.resolve(true) });

4.8. async managerApp.update(params)

Updates the firmware of the connected device.

NOTE: Should be only used in environments where both hw-hid and hw-serialport is supported.

Arguments:
params: IUpdateFirmwareParams

type GetDevices = () => Promise<IDevice[]>;

type CreateDeviceConnection = (device: IDevice) => Promise<IDeviceConnection>;

type UpdateFirmwareEventHandler = (event: UpdateFirmwareStatus) => void;

interface IUpdateFirmwareParams {
  // The firmware binary
  firmware?: Uint8Array;

  // The version of the firmware binary provided
  version?: IVersion;

  // Function to create a connection to the device. Should support both
  // `hw-hid` and `hw-serialport`
  createConnection: CreateDeviceConnection;

  // Function to get a list of connected devices. Should support both
  // `hw-hid` and `hw-serialport`
  getDevices: GetDevices;

  onProgress?: (progress: number) => void;
  onEvent?: UpdateFirmwareEventHandler;
}

Result: Promise<void>

Example:

await managerApp.updateFirmware({ createConnection, getDevices });