docs(sdk): add comprehensive SDK documentation and wire format reference

Covers all official SDKs (Rust, Go, Python, TypeScript, C FFI), the v2 wire format with method ID tables, authentication flow, and a build-your-own-SDK guide with implementation checklist.
2026-03-04 20:55:24 +01:00
parent 2d56824834
commit cbb76af6b1
8 changed files with 985 additions and 0 deletions
--- a/docs/sdk/index.md
+++ b/docs/sdk/index.md
@@ -0,0 +1,63 @@
+# quicproquo SDK Documentation
+
+This guide covers how to build clients for the quicproquo E2E encrypted messenger using the official SDKs or by implementing your own.
+
+## Official SDKs
+
+| Language | Location | Transport | Status |
+|---|---|---|---|
+| **Rust** | `crates/quicproquo-client` | QUIC + Cap'n Proto | Production |
+| **Go** | `sdks/go/` | QUIC + Cap'n Proto | Production |
+| **TypeScript** | `sdks/typescript/` | WebSocket bridge + WASM crypto | Production |
+| **Python** | `sdks/python/` | QUIC + Protobuf (v2) / Rust FFI | Production |
+| **C** | `crates/quicproquo-ffi/` | Rust FFI (synchronous) | Production |
+| **Swift** | `sdks/swift/` | C FFI wrapper | In progress |
+| **Kotlin** | `sdks/kotlin/` | JNI + C FFI | In progress |
+| **Java** | `sdks/java/` | JNI + C FFI | In progress |
+| **Ruby** | `sdks/ruby/` | FFI gem | In progress |
+
+## Documentation
+
+- [Wire Format](wire-format.md) -- v2 QUIC + Protobuf wire protocol
+- [Rust SDK](rust.md) -- Native Rust client
+- [Go SDK](go.md) -- Go client with QUIC transport
+- [Python SDK](python.md) -- Python client (async QUIC + sync FFI)
+- [TypeScript SDK](typescript.md) -- Browser/Node.js client with WASM crypto
+- [C FFI](c-ffi.md) -- C bindings for language integrations
+- [Build Your Own SDK](build-your-own.md) -- Guide for implementing a new language SDK
+
+## Architecture Overview
+
+```
+  Client SDK                     Server
+  ─────────                     ──────
+  ┌──────────┐   QUIC/TLS 1.3   ┌──────────┐
+  │ App code │ ◄──────────────► │ RPC      │
+  │          │   v2 wire frames  │ dispatch │
+  │ SDK API  │                   │          │
+  │          │   [method_id:u16] │ handlers │
+  │ Proto    │   [req_id:u32]    │          │
+  │ encode/  │   [len:u32]       │ storage  │
+  │ decode   │   [protobuf]      │          │
+  │          │                   │          │
+  │ QUIC     │                   │ QUIC     │
+  │ transport│                   │ listener │
+  └──────────┘                   └──────────┘
+```
+
+Each RPC call opens a new QUIC bidirectional stream. The request and response use the same 10-byte framing header followed by a protobuf payload.
+
+## Quick Start
+
+1. Choose an SDK for your language
+2. Connect to the server over QUIC (or WebSocket bridge for browsers)
+3. Authenticate with OPAQUE (register or login)
+4. Upload MLS key packages for E2E encryption
+5. Send and receive encrypted messages
+
+## Canonical Schemas
+
+- **Protobuf** (v2): `proto/qpq/v1/*.proto` -- 14 service definitions
+- **Cap'n Proto** (v1): `schemas/*.capnp` -- legacy RPC interface
+
+The protobuf schemas in `proto/qpq/v1/` are the canonical API contract for the v2 protocol. New SDKs should implement against these definitions.