Add NotesForge: notes-to-report CLI on the SuperDocs API - #64
Open
kathans22 wants to merge 4 commits into
Open
Conversation
A zero-dependency Node 20+/TypeScript CLI agent that turns a folder of rough notes into a finished, exported report using the SuperDocs https://docs.superdocs.app REST API.
Added a video link to the README for the NotesForge project.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the full NotesForge pipeline end to end: ingest a folder of rough notes → plan a report outline → generate the document async → verify structure and repair gaps → apply finishing touches → export to docx/pdf/html/markdown/txt.
Reuse-first credential handling (credentials.ts): checks SUPERDOCS_API_KEY, then ~/.superdocs/agent_credentials.json validated live via whoami, and only self-signs-up via POST /v1/agents/signup if both are empty or dead — verified live against the real API (a stale key from a prior session was correctly detected as 401 and fell through to a fresh, free signup).
Hard-capped operation budget (budget.ts): OpsLedger tracks ops_charged off every response and aborts before exceeding the cap (default 25), so a run can't silently blow through the 500 ops/month free tier.
Named error taxonomy in client.ts instead of bare Errors: AuthError (401), DocumentInUseError / TurnRevertedError (409, split by response code), QuotaError (429, no blind retry), ServerError (5xx, retried twice with backoff), NetworkError.
Async generation with full status-aware polling (pipeline.ts): uses POST /v1/chat/async + GET /v1/jobs/{id} instead of sync chat (which hits a ~300s gateway timeout), and distinguishes a continue_prompt pause (auto-resumed) from a genuine human-in-the-loop approval pause (surfaced, not silently resolved).
Free verification (verify.ts): checks the generated report's structure via the non-billed structure block on GET /v1/documents/{id} rather than spending an export just to confirm an edit landed; batches any repair into a single chat call and re-verifies once rather than looping.
Pre-signed transfer support for anything over 100KB, keeping large file bytes out of the agent's own context window.
CLI flags: --notes, --title, --out, --formats, --no-page-breaks, --plan-only, --whoami, --budget, --handoff, --ops-cap.
All response/request types (types.ts) are sourced from the live OpenAPI schema at api.superdocs.app/openapi.json, not guessed — including a few gaps the strict schema leaves untyped (awaiting_kind, the session-documents endpoint) filled in from the docs guides and confirmed live.
Non-goals / explicitly deferred: no web server or frontend, zero runtime dependencies (native fetch only; typescript/@types/node/tsx are dev-only).