docs(spec): client-facing API documentation design#153
Conversation
Design for docs/client-api.md — a single integrator-facing reference covering POST /auth, all client-facing NATS request/reply methods (room-service, history-service, search-service), the msg.send publish flow, and the server-pushed events triggered by each method on success and error paths. https://claude.ai/code/session_01MCqYvKJeDyockUPBM2Essv
|
Warning Rate limit exceeded
To continue reviewing without waiting, purchase usage credits in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughThis PR introduces a new client API design documentation specification that establishes conventions, formatting standards, and structural guidelines for the client-facing API reference. It defines required method coverage, per-method block formatting, HTTP/NATS subject conventions, and maintenance procedures. ChangesClient API Documentation Specification
Estimated code review effort🎯 2 (Simple) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/superpowers/specs/2026-05-06-client-api-doc-design.md`:
- Line 58: Fenced code blocks in the spec are missing a language tag (MD040);
update the three fences that begin near the "Overview", "Authenticate", and
"<Human-readable method name>" sections to use a language tag (e.g., change ```
to ```text) so markdownlint MD040 is satisfied; search for the three blocks that
start at the same places shown in the diff and prepend "text" (or an appropriate
language) to each opening ``` fence.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e56d953a-a853-425e-bad5-579122302f27
📒 Files selected for processing (1)
docs/superpowers/specs/2026-05-06-client-api-doc-design.md
|
|
||
| ## Top-level structure | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add fence languages for Markdown code blocks (MD040).
Line 58, Line 111, and Line 215 start fenced blocks without a language, which triggers markdownlint MD040.
Suggested fix
-```
+```text
1. Overview
2. Connection & Auth
...
-```
+```
-```
+```text
### Authenticate
...
-```
+```
-```
+```text
### <Human-readable method name>
...
-```
+```Also applies to: 111-111, 215-215
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 58-58: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/superpowers/specs/2026-05-06-client-api-doc-design.md` at line 58,
Fenced code blocks in the spec are missing a language tag (MD040); update the
three fences that begin near the "Overview", "Authenticate", and
"<Human-readable method name>" sections to use a language tag (e.g., change ```
to ```text) so markdownlint MD040 is satisfied; search for the three blocks that
start at the same places shown in the diff and prepend "text" (or an appropriate
language) to each opening ``` fence.
27-task plan to author docs/client-api.md covering POST /auth, all client-facing NATS request/reply methods (room-service, history-service, search-service), the msg.send publish flow, plus README/CLAUDE.md cross-links and a maintenance rule. https://claude.ai/code/session_01MCqYvKJeDyockUPBM2Essv
Adds the shared Message schema subsection (Cassandra Message row, Participant, QuotedParentMessage UDTs) and the Load History method block under §3.2 history-service, as the first of Tasks 14–21. https://claude.ai/code/session_01MCqYvKJeDyockUPBM2Essv
Appends the Edit Message RPC block under §3.2 history-service, covering request/response schemas, error cases, and the MessageEditedEvent triggered on success. https://claude.ai/code/session_01MCqYvKJeDyockUPBM2Essv
Appends the Delete Message RPC block under §3.2 history-service, covering request/response shapes, idempotency, sender-only auth, triggered events, and the CAS / already-deleted no-publish edge cases. https://claude.ai/code/session_01MCqYvKJeDyockUPBM2Essv
3 participants
Design for docs/client-api.md — a single integrator-facing reference
covering POST /auth, all client-facing NATS request/reply methods
(room-service, history-service, search-service), the msg.send publish
flow, and the server-pushed events triggered by each method on success
and error paths.
https://claude.ai/code/session_01MCqYvKJeDyockUPBM2Essv
Summary by CodeRabbit