minor api changes, added specs and types for public api functions