Updates

messaging-pubsub/hyper-p2p-qos-topic/docs/api.md

@@ -2,79 +2,84 @@
 
 **Protocol:** `qos-topic/v1`
 
-**Export:** `HyperP2PQosTopic`
+**Export:** `HyperP2PQosTopic`, `PROTOCOL`
 
 ## Overview
 
-Production p2p module: Hyperswarm discovery + Protomux when `topic` is set.
+Priority pub/sub with three QoS queues (0–2). Higher QoS messages drain before lower; subscribers declare minimum QoS per channel. Publishes gossip as `qos-publish`.
 
 ## Constructor
 
-```js
-const mod = new HyperP2PQosTopic(opts)
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `topic` | varies | null | topic |
-| `keyPair` | KeyPair | random Ed25519 | keyPair |
+| Option | Description |
+|--------|-------------|
+| `topic` | Hyperswarm topic |
+| `keyPair` | Publisher identity |
 
 ## Methods
 
-### `subscribe(channel, handler, qos = 0)`
+### `subscribe(channel, handler, qos?)`
 
-- **Returns:** `value`
-- **Throws:**
-  - `Error: handler must be a function`
+Default subscriber QoS `0`. Handler receives messages where `msg.qos >= sub.qos`.
 
-### `publish(channel, payload, opts = {})`
+### `publish(channel, payload, opts?)`
 
-- **Returns:** `value`
-- **Throws:** — (none documented in method body)
+- **opts.qos** — clamped 0–2
+- Enqueues then `_drain()` priority order
 
-### `pending(qos)`
+### `pending(qos?)`
 
-- **Returns:** `value`
-- **Throws:** — (none documented in method body)
+Queue depth for one level or total.
 
-### `getStats(—)`
+### `getStats()` / `ready()` / `close()`
 
-- **Returns:** `object`
-- **Throws:** — (none documented in method body)
+`published`, `delivered`, `gossipIn`, `gossipOut`.
 
-### `ready(—)`
+## Wire
 
-- **Returns:** `Promise`
-- **Throws:** — (none documented in method body)
-
-### `close(—)`
-
-- **Returns:** `Promise<void>`
-- **Throws:** — (none documented in method body)
+| type | fields |
+|------|--------|
+| `qos-publish` | `channel`, `payload`, `qos`, `from`, `at` |
 
 ## Events
 
-| Event | Payload |
-|-------|---------|
-| `message` | msg |
-
-## getStats()
-
-Returns `{ ...this._stats }` — typically `ops`, `errors`, and module-specific counters (`created`, `relays`, `open`, `peers`, etc.).
-Library-only modules may include `mode: 'local'`.
+`message`.
 
 ## Errors
 
-Stable message substrings: see [`../../_shared/ERROR_CODES.md`](../../_shared/ERROR_CODES.md).
+`assertNonEmpty(channel)`, invalid handler.
 
-## P2P
+## Composition
 
-When `topic` is set, `ready()` joins Hyperswarm and opens Protomux `qos-topic/v1`.
+`hyper-p2p-topic-channel` for retain; Wave 9 `qos-topic-two-node.js`.
 
 ## Testing
 
-```bash
-npm install && npm test
-```
+`npm test`, integration smoke.
 
-Integration: [`../../../real_tests/integration/qos-topic-two-node.js`](../../../real_tests/integration/qos-topic-two-node.js)
+## Example
+
+`examples/basic.js`
+
+## State model
+
+Three queues `_queues[0..2]`; drain processes highest index first.
+
+## Performance
+
+`pending()` walks all queues; bound publish rate if memory grows.
+
+## Versioning
+
+`qos-topic/v1` publish type unchanged since Wave 9.
+
+## Security
+
+No encryption; use `hyper-p2p-encrypted-topic` for sensitive channels.
+
+## Related modules
+
+- `hyper-p2p-topic-channel` — retain and subscribe
+
+## See also
+
+[`docs/architecture.md`](architecture.md)