wushenghua/hapi
1
0
Fork 0
mirror of https://github.com/wu736139669/hapi.git synced 2026-11-10 02:01:40 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: align documentation with current implementation

Browse Source
This commit is contained in:
weishu
2026-09-12 22:19:32 +08:00
parent dd9cfdcee5
commit 1de9613df6
27 changed files with 360 additions and 227 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/client-contract/index.md
+10 -3
View File
@@ -2,7 +2,7 @@
**Audience:** Implementers of native HAPI clients — the iOS app (`ios/`), the Android app (`android/`), and any other non-web client that talks to a hub's client API. These pages are the primary spec for that work: every claim is grounded in hub/web source, and each section names its source file so implementers (human or AI agent) can verify against code.
**Scope:** The HTTP contract between a client and one hub — pairing and auth, REST endpoints, SSE streaming, message pagination, message decoding, and error semantics. A client using only this contract can replicate the web app's core feature set over **REST + SSE alone** (no Socket.IO — that transport is CLI↔hub internal).
**Scope:** The HTTP contract between a client and one hub — pairing and auth, REST endpoints, SSE streaming, message pagination, message decoding, and error semantics. Core session/chat features use **REST + SSE**. Web terminals additionally use the JWT-authenticated Socket.IO `/terminal` namespace, outside this contract; `/cli` is the internal CLI↔hub namespace and is not a native-client API.
## Pages
@@ -39,8 +39,15 @@ Source of truth: `hub/src/web/server.ts` (`/health` route), `shared/src/version.
The prose in [Messages](./messages.md) describes the decoding tree, but the *normative* artifact is `shared/fixtures/` — machine-generated golden files produced from the web implementation's chat pipeline (`web/src/chat/`). A native client's protocol module must reproduce those fixtures exactly; CI regenerates them whenever the web pipeline changes, so drift is caught automatically.
`shared/fixtures/` is a companion deliverable of this contract and may not exist yet when you first read this — the fixture generator and batches land in later work packages of the same track. Until then, `web/src/chat/` itself is the reference implementation.
The fixtures and native conformance suites are present in this repository.
Regenerate fixtures from the repo root with `bun run gen:fixtures`; never
hand-edit generated JSON. See the native package READMEs for conformance checks.
## Relationship to the companion push contract
[`docs/api/native-companion-contract.md`](../native-companion-contract.md) is the **FCM push contract**: device registration (`POST /api/devices/register`) and the outbound push payload the hub sends through Firebase. It predates this contract and is unchanged. A native client implements *both*: this contract for everything interactive, the companion contract for background push. Where the two overlap (auth, send-message, approve/deny), this contract is the more detailed spec.
The [native companion contract](../native-companion-contract.md) specifies
Android/iOS device registration (`POST /api/devices/register`), encrypted
push envelopes, direct FCM/APNs delivery, and the shared push relay. A native
client implements this contract for interactive features and that contract
for background push. Where they overlap (auth, send-message, approve/deny),
this contract is the more detailed spec.