title_body: What's the correct way for developers to edit PDF?
upvoted_answer: The "problem" is that PDF does not know anything about its contents and the structure of the document (unless structure has been added — maybe in order to make it accessible). That means that you will have to find other ways to recognize (in the case of a TOC) titles etc. 
  
  One possibility (and I think PDFpen is doing it that way) is enumerating all text elements, comparing them with the properties you defined to be "Title", stitching them together (note that a word in PDF may not correspond to what we see as "word"), making a list of titles, creating another page, and create the TOC, and finally establish links between the TOC and the corresponding targets.
  
  Another thing to know is that it is way more complex to read a PDF than to write one. This is the reason why there are more libraries (and applications) to just write PDF than being able to read and write (and even fewer to understand PDF…).
  
  Now, because creating a TOC is something which does not happen that frequently, and requires a visual check anyway, it would be reasonable instead of trying to create an application to do it, to seriously consider a plug-in for Acrobat. Acrobat's API for plug-ins is rather extensive, and reasonably well documented, and there is a community which provides support. AFAIK, this API is free to use, unless you want the plug-in work with Reader (in that case, you will need a license from Adobe). The advantage of this approach is that you can rely on Acrobat's capabilities to write a proper, good quality PDF.
  
  To answer your (rather rhetoric) question why editing tools are so rare… Well, PDF is much more than a simple text file…