feat(docs): Help Scout Docs API — read commands (0.9) - #5
Merged
Conversation
Adds the Help Scout Docs API surface (separate product, separate per-user key): - DocsBaseCommand: skips Mailbox OAuth, builds a Docs client from the resolved key. - docs-client: HTTP Basic auth (key:X), host-locked to docsapi.helpscout.net, Docs envelope pagination, 429 + 5xx backoff. - docs-auth: resolveDocsKey (flag > HSCLI_DOCS_API_KEY env > keychain) + keychain docs-key storage. - hscli docs collection list (--site/--visibility/--limit + --output/--jq/--fields). - 100% coverage; live-verified read-only against a prod Docs account.
…s + docs auth - docs collection get; docs site list/get; docs category list - docs article list (--collection|--category, --status); docs article get; docs article search - docs auth: validate (read-only) + store the Docs key in the OS keychain - per-topic help descriptions; 100% coverage; live-verified read-only against prod
- Generated command reference now includes the docs topic (knowledge-base badge + guide link); 77 commands. - New guides/docs.mdx walkthrough (auth, sites, collections, categories, articles, search) + sidebar entry. - README: Docs API is shipped (not 'planned') — intro, commands table row, quick-start example.
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
- docs article create (POST, reload=true returns the new article), update (PUT, partial fields, errors if none), delete (DELETE 204, confirm unless --yes). - docs-input helper: @file text bodies + comma-separated lists. - 100% coverage (628 tests). Live-verified a full create -> update -> delete cycle against a prod Docs account using a throwaway notpublished article, then removed it; existing content untouched. - Docs site guide + generated reference + README updated for the write surface.
Complete the Docs API write surface: - docs collection create/update/delete - docs category create/update/delete - docs article save-draft/delete-draft Create/update use reload=true to return the resulting object; the Docs API requires --name on every collection/category update. Deletes prompt for confirmation unless --yes is passed. Drafts stage changes without affecting the published article. Regenerate the command reference (88 commands), update the Docs guide and README. 100% coverage retained.
Docs was only documented in its own guide + the generated reference. Wire it into the cross-cutting surfaces so the feature is discoverable: - overview: add the knowledge base to the capability list and Where-to-next - authentication: document the separate per-user Docs API key (hscli docs auth / HSCLI_DOCS_API_KEY) and add it to the env-var table - home: include `docs` in the search hint
Add a full-width featured recipe to the recipes band: an agent reads last week's inbox, spots the most-asked question, and publishes the answer to the Docs knowledge base — version-controlled and shipped from CI. Keeps the approved 3-up layout intact (the featured card spans the full row via grid-column 1/-1, copy left / terminal right, stacking under 760px). Verified light + dark.
Help Scout Docs API support — the hscli docs command group (auth, sites, collections, categories, articles incl. drafts) with full CRUD, plus docs site coverage and a home-page recipe. Regenerate the reference (88 cmds).
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
2 participants
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.
Adds the Docs API surface (separate Help Scout product, separate per-user API key).
Commands (read-focused)
hscli docs auth— validate (read-only) + store the Docs key in the OS keychain (orHSCLI_DOCS_API_KEY).docs site list/get,docs collection list/get,docs category list.docs article list(--collection/--category, --status),docs article get,docs article search.Design
docs-client: HTTP Basic auth (key:X), host-locked todocsapi.helpscout.net, Docs-envelope pagination, 429 + 5xx backoff.DocsBaseCommandskips the Mailbox OAuth flow; resolve key via flag → env → keychain.--output/--jq/--fields, sysexits exit codes.Quality
Writes (create/update/drafts) are intentionally out of scope here — roadmap.