feat: pubsub

[nugaon]

Add Pubsub Module

Introduces a new pubsub module that wraps Bee's (G)SOC-based PubSub WebSocket API, along with supporting types, tests and documentation.

What's added

• pubsubConnect(mode, handler, brokerPeer, ...params) — opens a WebSocket to GET /pubsub/:topicAddress and returns a subscription with send(payload) and cancel().
• listPubsubTopics() — GET /pubsub/ returning active topics with role (broker / subscriber / publisher) and connection info.
• GsocEphemeralMode — SOC-based pubsub mode implementing the IPubsubMode interface (topicAddress, getPublisherHeaders, encodeMessage, decodeMessage). Frame layout: [sig:65B][span:4B][payload].
• createPubsubMode(mode, ...) — generic factory with constructor-parameter inference keyed by the PubsubMode enum.

Three signer variants (discriminated union on GsocEphemeralParams)

• Ephemeral signer — { topic: string | Uint8Array }. A string is keccak256-hashed to derive the 32-byte private key; a Uint8Array / hex string is used as the private key directly. Can publish.
• External signer — { address, signFn }. Can publish; signs off-chunk via user-provided signFn. Address is carried in the swarm-pubsub-gsoc-eth-address header (hex, no 0x prefix).
• Subscriber-only — { topicAddress }. Read-only, no signer; getPublisherHeaders() returns null and encodeMessage() throws.

All variants support an optional socId (string → keccak256, or 32-byte Uint8Array; defaults to NULL_IDENTIFIER). For publisher variants, topicAddress is computed internally as makeSOCAddress(socIdentifier, signerAddress).

Other changes

• prepareWebsocketData made synchronous for consistency with websocket data types.
• Unit tests added for encode/decode round-trips, frame structure, deterministic headers, custom socId, external signer, subscriber-only mode, Uint8Array topic, and the mode factory.
• README Bee API table updated with pubsubConnect, listPubsubTopics, and gsocSubscribe.