Response Shape and Error Handling

SDK methods often return objects with a data field (e.g. { data: T }). You can destructure const { data } = await create(...) or use the extractResponseData helper. cilantro-react exports extractResponseData and extractErrorMessage; you can also implement them yourself (see below).

Response shape: extractResponseData

Use extractResponseData(response) to get the inner data from SDK responses. Types are exported from the same subpaths (e.g. WalletControllerCreateResult from cilantro-sdk/wallet).

function extractResponseData<T>(response: unknown): T | null {
  if (!response || typeof response !== 'object') return response as T | null;
  if ('data' in response) return (response as { data: T }).data as T;
  return response as T;
}

Example:

import { create, findAll } from 'cilantro-sdk/wallet';

const createResult = await create({ walletName: 'My Wallet' });
const wallet = extractResponseData(createResult); // { id, walletName, ... }

const listResult = await findAll();
const wallets = extractResponseData(listResult) ?? [];

Error handling: extractErrorMessage

SDK calls can throw or return error-shaped responses. Use a small utility to get a user-facing message:

function extractErrorMessage(error: unknown): string {
  if (error instanceof Error) return error.message;
  if (typeof error === 'object' && error !== null && 'response' in error) {
    const r = (error as { response?: { data?: { message?: string } } }).response;
    if (r?.data?.message) return r.data.message;
  }
  return String(error);
}

Example:

try {
  const result = await create({ walletName: 'My Wallet' });
  const wallet = extractResponseData(result);
} catch (e) {
  console.error(extractErrorMessage(e));
}

For device key not found (email/phone signers), show a clear message such as: "Re-create the signer on this device" or prompt the user to log in again on this device.

Using both together

try {
  const result = await create({ walletName: 'My Wallet' });
  const wallet = extractResponseData(result);
  if (!wallet) throw new Error('No wallet returned');
  return wallet;
} catch (e) {
  const message = extractErrorMessage(e);
  toast.error(message);
  throw e;
}

For SDK error classes and recovery strategies (e.g. DeviceKeyNotFoundError, DeviceKeyMismatchError), see Error Handling.

Next steps