updated lib & readme to reflect the new API behaviour