Hooks and Errors

Copyawait client.bridge(params, {
  hooks: {
    onIntent: ({ intent, allow }) => allow(),
    onAllowance: ({ allow }) => allow(['min']),
  },
});

Copytype Event =
  | { type: 'status'; status: string }
  | { type: 'plan_preview'; plan: /* plan */ }
  | { type: 'plan_confirmed'; plan: /* plan */ }
  | { type: 'plan_progress'; stepType: string; state: string; step: /* step */ };
 
type OnEventParam<TEvent> = {
  onEvent?: (event: TEvent) => void;
};

Copyawait client.bridge(params, {
  onEvent: (event) => {
    if (event.type === 'plan_progress') {
      console.log('Step:', event.stepType, event.state);
    }
  },
});

Copytype OnIntentHookData = {
  allow: () => void;
  deny: () => void;
  intent: BridgeIntent;
  refresh: (selectedSources?: number[]) => Promise<BridgeIntent>;
};

Copytype BridgeIntent = {
  provider: 'nexus' | 'mayan';
  availableSources: Array<{
    amount: string;
    amountRaw: bigint;
    chain: { id: number; name: string; logo: string };
    token: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
    value: string;
  }>;
  selectedSources: Array<{
    amount: string;
    amountRaw: bigint;
    chain: { id: number; name: string; logo: string };
    token: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
    value: string;
  }>;
  destination: {
    amount: string;
    amountRaw: bigint;
    chain: { id: number; name: string; logo: string };
    token: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
    value: string;
    nativeAmount: string;
    nativeAmountRaw: bigint;
    nativeAmountValue: string;
    nativeAmountInToken: string;
    nativeToken: { decimals: number; symbol: string; logo: string; contractAddress: Hex };
  };
  fees: {
    caGas: string;
    protocol: string;
    solver: string;
    total: string;
    totalValue: string;
  };
  sourcesTotal: string;
  sourcesTotalValue: string;
};

Copyawait client.bridge(params, {
  hooks: {
    onIntent: async ({ intent, allow, deny, refresh }) => {
      // Render the plan and fees from `intent`
      if (userChangedSources) {
        const updated = await refresh([10, 42161]); // re-plan against Optimism + Arbitrum
        // re-render with `updated`
      }
      if (userApproves) allow();
      else deny();
    },
  },
});

Copytype OnAllowanceHookData = {
  allow: (values: Array<'max' | 'min' | bigint | string>) => void;
  deny: () => void;
  sources: AllowanceHookSource[];
};
 
type AllowanceHookSource = {
  allowance: {
    current: string;     // Current allowance (human-readable)
    currentRaw: bigint;  // Current allowance (raw)
    minimum: string;     // Minimum required (human-readable)
    minimumRaw: bigint;  // Minimum required (raw)
  };
  chain: {
    id: number;
    logo: string;
    name: string;
  };
  holderAddress?: Hex;
  token: {
    contractAddress: `0x${string}`;
    decimals: number;
    logo: string;
    name: string;
    symbol: string;
  };
};

Copyawait client.bridge(params, {
  hooks: {
    onAllowance: ({ sources, allow, deny }) => {
      // `sources` has one entry per approval required
      if (userApproves) allow(sources.map(() => 'min')); // or 'max' / custom per source
      else deny();
    },
  },
});

Copytype OnIntentHookData = {
  allow: () => void;
  deny: () => void;
  intent: SwapIntent;
  refresh: (sources?: Source[]) => Promise<SwapIntent>;
};

Copyawait client.swapWithExactIn(input, {
  hooks: {
    onIntent: ({ intent, allow }) => {
      // Render the route and destination amount from `intent`
      allow();
    },
  },
});

Copytype BridgeAndExecuteOnIntentHookData = {
  allow: () => void;
  deny: () => void;
  intent: BridgeAndExecuteIntent;
  refresh: (selectedSources?: number[]) => Promise<BridgeAndExecuteIntent>;
};
 
type SwapAndExecuteOnIntentHookData = {
  allow: () => void;
  deny: () => void;
  intent: SwapAndExecuteIntent;
  refresh: (sources?: Source[]) => Promise<SwapAndExecuteIntent>;
};

Copyawait client.bridgeAndExecute(params, {
  onIntent: ({ intent, allow, deny }) => {
    // `intent.bridgeRequired` tells you whether a bridge leg is needed
    if (userApproves) allow();
    else deny();
  },
});

Copyabstract class NexusError extends Error {
  readonly category: ErrorCategory; // set by each subclass
  readonly code: ErrorCode;         // namespaced string, e.g. 'validation/insufficient_balance'
  readonly context: ErrorContext;   // { operation?, service?, stepId?, stepType?, chainId? }
  readonly details?: Record<string, unknown>;
 
  toJSON(): object; // serializable { name, message, category, code, context, details }
}
 
type ErrorCategory =
  | 'validation'
  | 'user_action'
  | 'simulation'
  | 'execution'
  | 'backend'
  | 'external_service'
  | 'internal';

Copyimport {
  NexusError,
  UserActionError,
  ValidationError,
  ERROR_CODES,
} from '@avail-project/nexus-core';
 
try {
  await client.bridge({ toTokenSymbol: 'USDC', toAmountRaw: 1_000_000n, toChainId: 137 });
} catch (error) {
  if (error instanceof NexusError) {
    console.error(`[${error.category}] ${error.code}: ${error.message}`);
 
    // Coarse branching on category
    if (error instanceof UserActionError) {
      // User cancelled a prompt — usually nothing to show
      return;
    }
 
    if (error instanceof ValidationError) {
      switch (error.code) {
        case ERROR_CODES.INSUFFICIENT_BALANCE:
          showInsufficientBalanceUI();
          break;
        case ERROR_CODES.TOKEN_NOT_SUPPORTED:
          showUnsupportedTokenUI();
          break;
        default:
          showGenericError(error.message);
      }
    }
 
    // Log the structured form for telemetry
    logErrorToService(error.toJSON());
  } else {
    // Non-Nexus errors (network, library, etc.)
    console.error('Unexpected error:', error);
  }
}