@solarpunkltd/swarm-chat-js 6.2.8 → 7.0.0

package/README.md

@@ -1,214 +1,193 @@
-# Swarm Chat JS Library 🐝💬
-
-The core client-side library for building decentralized chat applications over [Swarm](https://www.ethswarm.org/). This library provides the essential logic for sending, receiving, and managing chat messages within a Swarm ecosystem.
-
-**Important Note:** `swarm-chat-js` is designed to work in conjunction with a companion aggregator server. It is **not functional as a standalone library** for a complete chat system. The aggregator is responsible for collecting messages broadcast by users and consolidating them into a shared chat feed.
-
-The current reference implementation works with the [Solar-Punk-Ltd/swarm-chat-aggregator-js](https://github.com/Solar-Punk-Ltd/swarm-chat-aggregator-js).
-
----
-
-## ⚙️ How It Works
-
-`swarm-chat-js` enables decentralized communication by leveraging Swarm's features like Feeds and GSOC.
-
-**Conceptual Overview:**
-
-Users broadcast their messages via updates to their personal Swarm feeds, with notifications sent to a pre-defined GSOC address. A dedicated **aggregator server** listens to this GSOC message. When new message notifications arrive, the aggregator fetches the message content, processes it, and then writes it to a common, persistent, protected Swarm feed (the "chat feed"). Client applications polling this aggregated chat feed to display messages to users (built into `swarm-chat-js`).
-
-**Message Flow:**
-
-1.  **User Sends Message:** A user types and sends a message using an application built with `swarm-chat-js`.
-    - The message is written to the user's own Swarm feed.
-    - An update is broadcast to a designated GSOC address.
-2.  **Aggregator Receives & Processes:** The aggregator server, subscribed to the GSOC address, receives the update.
-    - It may perform validation or other processing steps.
-3.  **Aggregator Writes to Chat Feed:** The aggregator writes the processed message to the main, shared "chat feed".
-4.  **Client App Reads:** `swarm-chat-js` in other users' applications either:
-    - **Polling mode**: Polls the main chat feed for new messages and displays them
-    - **Waku mode**: Receives real-time message updates via the Waku network
-
----
-
-## 📦 Installation
-
-You can install the library using npm or pnpm:
+# Swarm Chat JS
+
+A client library for chat over [Swarm](https://www.ethswarm.org/). A browser signs each message and sends it as one
+GSOC write to a shared inbox. A chat server verifies it and publishes it to the chat's feed, and every reader follows
+that feed. The browser talks only to a Bee node or gateway, never to a web server of its own.
+
+The library needs its server,
+[Solar-Punk-Ltd/swarm-chat-aggregator-js](https://github.com/Solar-Punk-Ltd/swarm-chat-aggregator-js), which listens on
+the inbox and writes the feed. Version 7 of the library reads and writes the v7 message format only.
+
+## How it works
+
+1. **Sending.** The sender builds the message, signs it with the user's key, and writes it once to the inbox, a GSOC
+   address every chat shares. The message stays pending until the chat feed shows it. If it does not, the identical
+   bytes are written again every ten seconds, up to five times, and then it is failed with a manual retry.
+2. **Publishing.** The server checks each message's shape and signature and writes it to the chat's feed as the next
+   entry, at index 0, 1, 2 and on. After a message is published it saves a history file of the chat, and every entry
+   links to the newest file saved.
+3. **Opening.** A reader asks Bee for the feed's head once, shows the history file the head entry links to, and reads
+   the entries after it.
+4. **Following.** A reader polls explicit feed slots after the last one it saw, several in one poll. A slot not
+   written yet is the ordinary live state and is simply asked again. A slot that fails its checks is skipped and never
+   stops the chat. A slot no peer gives out while later slots exist is stepped past and read again on later polls, so a
+   message skipped arrives late rather than never. Gateway failures back off with jitter up to eight seconds.
+5. **Older messages.** Loading older messages is a click, which reads the history file before the oldest one shown.
+
+## Installation
 
 ```bash
-npm/pnpm install @solarpunkltd/swarm-chat-js
+pnpm add @solarpunkltd/swarm-chat-js @ethersphere/bee-js
 ```
 
----
+bee-js 13 is a peer dependency. The package runs in browsers and in Node 24 or later, as ESM or CommonJS.
 
-## 🛠️ Core Concepts & API
+## Usage
 
-### Imports
+```ts
+import { EVENTS, MessageType, SwarmChat, type MessageData } from '@solarpunkltd/swarm-chat-js';
 
-```typescript
-import { EVENTS, MessageData, MessageType, SwarmChat, ChatSettings } from '@solarpunkltd/swarm-chat-js';
-```
-
-### `ChatSettings` Interface
-
-This configuration object is crucial for initializing the `SwarmChat` instance.
-
-```typescript
-export interface ChatSettings {
-  user: {
-    /** Private key of the chat user, used for signing updates to their own Swarm feed. */
-    privateKey: string;
-    /** Display name or nickname of the current user. */
-    nickname: string;
-  };
+const chat = new SwarmChat({
+  user: { privateKey: userKey, nickname: 'alice' },
   infra: {
-    /** URL of the Bee node used by the client to write to their own feed and to poll the aggregated chat feed. */
-    beeUrl: string;
-    /**
-     * If true, a postage stamp (`stamp` property) must be provided for uploading messages.
-     * The stamp does not necessarily need to be tied to the `beeUrl` node; it can be an independent stamp. (Enveloped stamp)
-     */
-    enveloped: boolean;
-    /** Optional: Postage stamp ID. Required if `enveloped` is true, unless `beeUrl` points to a gateway with auto-stamping capabilities. */
-    stamp?: string;
-    /** The mined GSOC topic string where users broadcast updates about their new messages. */
-    gsocTopic: string;
-    /** The mined GSOC resource ID (address) associated with the `gsocTopic`. */
-    gsocResourceId: string;
-    /** The topic of the aggregated chat feed, written by the aggregator server. */
-    chatTopic: string;
-    /** The public address (Swarm feed address) of the aggregated chat feed, written by the aggregator. */
-    chatAddress: string;
-    /** Enable real-time messaging via Waku network. When true, messages are received instantly instead of polling. */
-    waku: boolean;
-  };
-}
+    beeUrl: 'https://gateway.example.com',
+    gsocTopic: inboxIdentifier,
+    gsocResourceId: minedInboxKey,
+    chatTopic: 'chat-my-stream',
+    chatAddress: serverFeedOwner,
+    pollingInterval: 500,
+  },
+});
+
+const { on } = chat.getEmitter();
+on(EVENTS.MESSAGE_RECEIVED, (message: MessageData) => show(message));
+on(EVENTS.MESSAGE_REQUEST_ERROR, (message: MessageData) => offerRetry(message));
+on(EVENTS.STATUS, (status) => showConnection(status));
+
+await chat.start();
+await chat.sendMessage('hello', MessageType.TEXT);
+await chat.sendMessage('👍', MessageType.REACTION, someMessageId);
+
+// Later, and in any order, as often as needed.
+await chat.stop();
 ```
 
-### Events (`EVENTS`)
-
-The library emits several events that your application can subscribe to for reacting to different stages of the chat lifecycle. Use `SwarmChat.getEmitter().on(EVENT_NAME, callback)` to subscribe.
-
-- `EVENTS.LOADING_INIT`: ('loadingInit')
-  Fired when the chat library begins its initialization process.
-- `EVENTS.LOADING_PREVIOUS_MESSAGES`: ('loadingPreviousMessages')
-  Fired when the library is actively loading previous messages from the chat feed.
-- `EVENTS.MESSAGE_RECEIVED`: ('messageReceived')
-  A new message has been successfully received from the aggregated chat feed and processed by the client.
-- `EVENTS.MESSAGE_REQUEST_INITIATED`: ('messageRequestInitiated')
-  The current user has initiated the process of sending a new message.
-- `EVENTS.MESSAGE_REQUEST_UPLOADED`: ('messageRequestUploaded')
-  The current user's message has been successfully uploaded to their own feed. (Note: The broadcast to the GSOC for aggregator pickup can still be pending or fail after this event).
-- `EVENTS.MESSAGE_REQUEST_ERROR`: ('messageRequestError')
-  An error occurred during the message sending process (either uploading to the user's feed or broadcasting via GSOC).
-- `EVENTS.CRITICAL_ERROR`: ('criticalError')
-  The library has encountered a critical, potentially unrecoverable error.
-
-### Main `SwarmChat` Methods
-
-The `SwarmChat` class instance provides the following core methods:
-
-- `start()`: Initializes and starts the chat service, including setting up listeners and beginning to poll for messages.
-- `stop()`: Stops the chat service, clears intervals, and cleans up resources.
-- `getEmitter()`: Returns an event emitter instance, allowing your application to subscribe to the `EVENTS` listed above.
-- `sendMessage(message: string, type: MessageType, targetMessageId?: string, id?: string)`: Initiates the process of sending a new chat message from the current user. Supports different message types including text, threads, and reactions.
-- `fetchPreviousMessages()`: Manually triggers the fetching of older messages from the aggregated chat feed.
-- `hasPreviousMessages()`: Returns a boolean indicating whether there are previous messages available to fetch (determined by checking if more than one message state reference exists).
-- `retrySendMessage(message: MessageData)`: Attempts to resend a message that previously encountered an error during the initial request phase (e.g., failed to write to the user's own feed).
-- `retryBroadcastUserMessage(message: MessageData)`: Attempts to re-broadcast a message update via GSOC if the message was successfully uploaded to the user's feed but the GSOC broadcast might have failed or needs retrying.
-
-### Message Types
-
-The library supports three types of messages through the `MessageType` enum:
-
-- `MessageType.TEXT`: Regular chat messages
-- `MessageType.THREAD`: Reply messages that reference a parent message via `targetMessageId`
-- `MessageType.REACTION`: Emoji reactions to existing messages, also using `targetMessageId` to reference the target message
-
-### Message State Management
-
-The library includes robust message state handling with:
-
-- **Automatic retry logic**: Failed message state references are automatically retried with exponential backoff
-- **Ref banning**: Persistently failing references are banned after maximum retry attempts to prevent infinite loops
-- **Efficient caching**: Message state data is cached to avoid redundant network requests
-
----
-
-## 🚀 Usage Example (React)
-
-Here's an example of how `swarm-chat-js` can be integrated into a React application using a custom hook (`useSwarmChat`). This hook encapsulates chat logic, state management, and event handling.
-
-### Complete Implementation
-
-For a full working example, check out our React integration:
-
-**📖 [View Complete useSwarmChat Hook Implementation](https://github.com/Solar-Punk-Ltd/swarm-chat-react-example/blob/master/src/hooks/useSwarmChat.tsx)**
-
-### Basic Usage
-
-```typescript
-import { useSwarmChat } from './hooks/useSwarmChat';
-import { MessageType } from '@solarpunkltd/swarm-chat-js';
-
-function ChatComponent() {
-  const { messages, isLoading, sendMessage, hasPreviousMessages, loadPreviousMessages } = useSwarmChat(chatSettings);
-
-  const handleSendMessage = (text: string) => {
-    sendMessage(text, MessageType.TEXT);
-  };
-
-  const handleReaction = (targetMessageId: string, emoji: string) => {
-    sendMessage(emoji, MessageType.REACTION, targetMessageId);
-  };
-
-  const handleReply = (targetMessageId: string, replyText: string) => {
-    sendMessage(replyText, MessageType.THREAD, targetMessageId);
-  };
-
-  return (
-    <div className="chat-container">
-      {/* Your chat UI implementation */}
-      {hasPreviousMessages() && <button onClick={loadPreviousMessages}>Load Previous Messages</button>}
-      {/* Message list, input field, etc. */}
-    </div>
-  );
-}
+## Settings
+
+| Setting                  | Meaning                                                                                                                            |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `user.privateKey`        | Signs every message. A viewer that only reads may pass any key.                                                                    |
+| `user.nickname`          | The name on every message, 1 to 20 characters. Nothing can be sent without one.                                                    |
+| `infra.beeUrl`           | The Bee node or gateway every read and write goes through.                                                                         |
+| `infra.stamp`            | The batch the inbox writes are stamped with. Left out for a gateway that stamps writes itself.                                     |
+| `infra.gsocTopic`        | The inbox's identifier string, the same for every chat.                                                                            |
+| `infra.gsocResourceId`   | The mined key every sender signs inbox writes with. The server's operator mines it.                                                |
+| `infra.chatTopic`        | The chat's topic, which every message carries and the feed is named by.                                                            |
+| `infra.chatAddress`      | The server's feed owner address.                                                                                                   |
+| `infra.pollingInterval`  | How often a reader polls at the live edge, 1,000 ms by default.                                                                    |
+| `infra.socReadTimeout`   | One feed slot read, 5,000 ms by default.                                                                                           |
+| `infra.feedReadTimeout`  | The head lookup and a history file download, 15,000 ms by default. A head lookup that runs out of time reads the chat from slot 0. |
+| `infra.gsocWriteTimeout` | One inbox write, 10,000 ms by default.                                                                                             |
+
+## Methods
+
+| Method                                      | What it does                                                                                                                                                                                                                                                                       |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start()`                                   | Opens the chat and follows it. Resolves once it is open, or once `stop` is called. Opening is retried for as long as the chat runs.                                                                                                                                                |
+| `stop()`                                    | Stops every poll, resend and retry. Listeners stay, so a later `start` reports to them again.                                                                                                                                                                                      |
+| `getEmitter()`                              | The events below, with `on` and `off`.                                                                                                                                                                                                                                             |
+| `sendMessage(text, type, targetMessageId?)` | Sends a text or a thread reply and resolves to the pending message. A reaction resolves to `null`: taps on one reaction inside a second cancel in pairs, and only an odd count is sent. Rejects with a `ChatMessageError`, sending nothing, for a message the server would refuse. |
+| `retrySendMessage(message)`                 | Writes a failed or pending message again with its identical bytes.                                                                                                                                                                                                                 |
+| `fetchPreviousMessages()`                   | Shows the history file before the oldest one shown, and resolves to its messages.                                                                                                                                                                                                  |
+| `hasPreviousMessages()`                     | Whether there is an older file to load.                                                                                                                                                                                                                                            |
+| `orderMessages(messages)`                   | Published messages in chat order, then pending ones by time.                                                                                                                                                                                                                       |
+| `getStatus()`                               | `live`, `reconnecting`, `stalled`, or `null` before the first read.                                                                                                                                                                                                                |
+| `getAddress()`                              | The address of the key, which is every sent message's `address`.                                                                                                                                                                                                                   |
+
+## Events
+
+| Event                       | Carries          | When                                                                                                                            |
+| --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `LOADING_INIT`              | `boolean`        | `true` when opening starts, `false` once the chat is open.                                                                      |
+| `LOADING_PREVIOUS_MESSAGES` | `boolean`        | Around a load of older messages.                                                                                                |
+| `MESSAGE_RECEIVED`          | `MessageData`    | A message the feed or a history file shows. For a sender, this is what "sent" means.                                            |
+| `MESSAGE_REQUEST_INITIATED` | `MessageData`    | A message signed and about to be written, with `index` -1.                                                                      |
+| `MESSAGE_REQUEST_UPLOADED`  | `MessageData`    | Its first write the node accepted. It is still pending.                                                                         |
+| `MESSAGE_REQUEST_ERROR`     | `MessageData`    | Its resends ran out unseen.                                                                                                     |
+| `STATUS`                    | `FeedStatus`     | `live`: the gateway answers. `reconnecting`: it does not. `stalled`: a message known to exist has not loaded for eight seconds. |
+| `MESSAGE_SKIPPED`           | `SkippedMessage` | A feed slot or history row not shown, and why.                                                                                  |
+| `ERROR`                     | `unknown`        | A failure the chat recovers from on its own.                                                                                    |
+| `CRITICAL_ERROR`            | `unknown`        | Opening failed three times in a row. It keeps trying.                                                                           |
+
+**The order of a sent message's events.** `MESSAGE_REQUEST_INITIATED` comes first, then `MESSAGE_REQUEST_UPLOADED`
+once a write is accepted, then `MESSAGE_RECEIVED` when the feed shows it. The resends and the give-up wait while the
+status is not `live`, so a message is not failed only because this viewer could not see the feed. A message can still
+be failed and then shown, for example when the server published it after the last resend, so `MESSAGE_RECEIVED` may
+follow `MESSAGE_REQUEST_ERROR` for the same `id`, and a viewer settles on the received one.
+
+A `MessageData` has `id`, `type`, `message` (the text or emoji), `username`, `address`, `timestamp` (the server's
+receive time, or the sender's clock while pending), `targetMessageId` for a reply or reaction, `chatTopic`,
+`signature`, `index` (the feed index, -1 while pending) and `sentAt` (the sender's clock, which nothing checks).
+
+## The message, for servers and tools
+
+`@solarpunkltd/swarm-chat-js/message` is the one place the message is built, signed and checked, and the server imports
+it rather than keeping a copy. It loads none of the reader.
+
+```ts
+import { parseChatMessage, MAX_MESSAGE_BYTES } from '@solarpunkltd/swarm-chat-js/message';
+
+const check = parseChatMessage(payload);
+if (check.ok) publish(check.message);
+else count(check.reason);
 ```
 
----
-
-## ⛏️ Helper Scripts
-
-### Mine GSOC Address
-
-The library provides a helper script to mine a GSOC address and topic. This is typically used when setting up your aggregator server.
-
-**Usage:**
+A message is a JSON object of at most 2,048 bytes of UTF-8:
+
+| Field    | Meaning                                                                                                      |
+| -------- | ------------------------------------------------------------------------------------------------------------ |
+| `v`      | `7`                                                                                                          |
+| `topic`  | The chat's topic, 1 to 128 characters                                                                        |
+| `id`     | A random id, 32 lowercase hex characters                                                                     |
+| `type`   | `text`, `thread` (a reply, `target` is the parent) or `reaction` (`target` is the message, `text` the emoji) |
+| `target` | The id it refers to, or `""` for a text                                                                      |
+| `text`   | 1 to 500 characters                                                                                          |
+| `name`   | 1 to 20 characters                                                                                           |
+| `addr`   | The sender's address, 40 lowercase hex characters without `0x`                                               |
+| `ts`     | The sender's clock in milliseconds                                                                           |
+| `sig`    | 130 hex characters                                                                                           |
+
+Characters are counted as Unicode code points, so an emoji counts once, and `countCharacters` counts the same way for
+a composer. The signed bytes are the UTF-8 of `JSON.stringify([7, topic, id, type, target, text, name, addr, ts])`,
+signed with bee-js's `PrivateKey.sign` and checked with `Signature.recoverPublicKey`, both over the raw bytes.
+
+| Export                                                                       | Use                                                                                         |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `parseChatMessage(bytes)`                                                    | The server's check of a raw payload: byte cap, UTF-8, JSON, shape, signature. Never throws. |
+| `checkChatMessage(value)`                                                    | The same for a parsed object.                                                               |
+| `createChatMessage(key, draft)`                                              | Builds and signs, throwing a `ChatMessageError` for anything the check would refuse.        |
+| `chatMessageSchema`, `hasValidSignature`, `signedBytes`, `encodeChatMessage` | The parts.                                                                                  |
+| `feedEntrySchema`, `parseFeedEntry`                                          | The feed entry, `{v, seq, at, msg, history}`.                                               |
+| `historyFileSchema`, `parseHistoryFile`                                      | The history file, `{v, topic, fromSeq, toSeq, messages, prev}`.                             |
+
+## Changes from 6.x
+
+- Messages are signed over every field and verified by the server. 6.x signed four fields with a double prefix, and its
+  check passed forged messages.
+- One inbox write per message. The write to the sender's own feed is gone, and so are `userTopic`, `additionalProps`,
+  and the `enveloped` setting.
+- A bad message or history row is skipped, never a freeze. A slot no peer gives out is stepped past and read again.
+- No signature check per message on the read path, which cost 6.x about 36 ms of main thread per message on every open.
+- `sendMessage` takes three arguments, and a reaction resolves to `null`. `retrySendMessage` covers what
+  `retryBroadcastUserMessage` did.
+- `stop` keeps listeners. New events: `STATUS`, `MESSAGE_SKIPPED` and `ERROR`. `CRITICAL_ERROR` means three failed
+  openings in a row, and opening keeps trying.
+- `MessageData.index` is the feed index, `timestamp` is the server's receive time, and `sentAt` is new.
+- The GSOC mining script moved to the server repository, whose operator mines the inbox key.
+- The package is ESM first with a CommonJS build. The UMD bundle and the Node polyfills are gone.
+
+## Development
+
+Node 24 and pnpm 12, through `packageManager`.
 
 ```bash
-npm run mine -- <bee-address> <topic-name>
+pnpm install
+pnpm test
 ```
 
----
-
-## ⚠️ Limitations
-
-- **Polling Mechanism:** The current version of `swarm-chat-js` relies on polling the aggregator's chat feed to fetch new messages. This approach can be resource-heavy.
-
----
-
-## 💡 Future Development
-
-- **Push-Based Event System:** We are actively designing a new architecture to transition from the polling mechanism to a more efficient, push-based event system for message delivery. This will significantly reduce node load and improve real-time message propagation.
-- **Performance Optimizations:** Further improvements to message state handling and caching mechanisms.
-
----
-
-## 📚 Further Reading & Resources
+`lint` (oxlint, type-aware), `format` and `format:check` (oxfmt), `typecheck`, `test` (vitest) and `build` (vite, with
+types from `tsc`) are the scripts CI runs. `pnpm pack` builds before it packs.
 
-- [What are Feeds? (Official Swarm Documentation)](https://docs.ethswarm.org/docs/develop/tools-and-features/feeds#what-are-feeds)
-- [GSOC Introduction (Official Swarm Documentation)](https://docs.ethswarm.org/docs/develop/tools-and-features/gsoc/#introduction)
-- [Example Aggregator: Solar-Punk-Ltd/swarm-chat-aggregator-js](https://github.com/Solar-Punk-Ltd/swarm-chat-aggregator-js)
-- [Example React client](https://github.com/Solar-Punk-Ltd/swarm-chat-react-example)
+## License
 
----
+Apache-2.0

package/dist/chat.d.ts

@@ -0,0 +1,106 @@
+import { ChatEmitter, type MessageData } from './events.js';
+import { FeedStatus, type FollowerSettings } from './follower.js';
+import { MessageType } from './message/index.js';
+import { type GsocWrite, type SenderSettings } from './sender.js';
+import { type ChatSource } from './swarm.js';
+export interface ChatSettings {
+    user: {
+        /** Signs every message. A viewer that only reads may pass any key, since nothing is sent without a nickname. */
+        privateKey: string;
+        /** The name shown on every message, 1 to 20 characters. */
+        nickname: string;
+    };
+    infra: {
+        /** The Bee node or gateway every read and write goes through. */
+        beeUrl: string;
+        /** The batch the inbox writes are stamped with. Left out for a gateway that stamps writes itself. */
+        stamp?: string;
+        /** The inbox's identifier string, one for every chat, as the server listens on it. */
+        gsocTopic: string;
+        /** The mined key every sender signs inbox writes with, which puts them in the server node's neighbourhood. */
+        gsocResourceId: string;
+        /** The chat's topic, which every message carries and the server's feed is named by. */
+        chatTopic: string;
+        /** The server's feed owner address. */
+        chatAddress: string;
+        /** How often the reader polls at the live edge, 1,000 ms by default. */
+        pollingInterval?: number;
+        /**
+         * The head lookup and a history file download, 15,000 ms by default. An idle Bee answers the head lookup of a
+         * 1,000 message chat in about five seconds, so this is three times that. A lookup slower than this is a loaded
+         * gateway, and the chat is then read from slot 0 rather than waiting on it.
+         */
+        feedReadTimeout?: number;
+        /** One inbox write, 10,000 ms by default. */
+        gsocWriteTimeout?: number;
+        /** One feed slot read, 5,000 ms by default. */
+        socReadTimeout?: number;
+    };
+}
+/** What a test hands in instead of the network, and the tuning a test shortens. */
+export interface ChatParts {
+    source: ChatSource;
+    write: GsocWrite;
+    follower: Partial<FollowerSettings>;
+    sender: Partial<SenderSettings>;
+    /** The waits between opening attempts, the last repeated. */
+    openRetryMs: readonly number[];
+}
+/**
+ * One chat: opens it from its newest history file, follows its feed, and sends messages to the server's inbox. Its
+ * events carry everything a viewer shows, and `start` and `stop` may be called in any order and any number of times.
+ */
+export declare class SwarmChat {
+    private readonly emitter;
+    private readonly key;
+    private readonly topic;
+    private readonly nickname;
+    private readonly source;
+    private readonly write;
+    private readonly senderSettings;
+    private readonly openRetryMs;
+    private readonly follower;
+    private readonly history;
+    private sender;
+    private readonly seen;
+    private status;
+    private generation;
+    private running;
+    private starting;
+    private openTimer;
+    private wakeOpen;
+    constructor(settings: ChatSettings, parts?: Partial<ChatParts>);
+    getEmitter(): ChatEmitter;
+    /** The reader's state, or null before the chat has been read. */
+    getStatus(): FeedStatus | null;
+    /** This key's address, the `address` of every message it sends. */
+    getAddress(): string;
+    /**
+     * Opens the chat and starts following it. Resolves once it is open, or once `stop` is called first. Opening is
+     * retried with backoff for as long as the chat runs: every failure is an ERROR event, and three in a row a
+     * CRITICAL_ERROR.
+     */
+    start(): Promise<void>;
+    /** Stops every poll, resend and retry. Listeners stay, so a later `start` reports to them again. */
+    stop(): Promise<void>;
+    /**
+     * Sends a text or a thread reply, or taps a reaction. A text and a reply resolve to the pending message, which
+     * MESSAGE_RECEIVED later shows as published. A reaction resolves to null: taps inside a second cancel in pairs,
+     * and only an odd count is sent. Rejects with a ChatMessageError, sending nothing, for a message the server would
+     * refuse, such as one with no nickname.
+     */
+    sendMessage(text: string, type: MessageType, targetMessageId?: string): Promise<MessageData | null>;
+    /** Sends a failed or pending message again, with its identical bytes. Returns whether it was still held. */
+    retrySendMessage(message: MessageData | string): boolean;
+    /** Loads the history file before the oldest one shown, and shows its messages. */
+    fetchPreviousMessages(): Promise<MessageData[]>;
+    hasPreviousMessages(): boolean;
+    /** Published messages in chat order, then pending ones by the sender's clock. */
+    orderMessages<T extends Pick<MessageData, 'index' | 'timestamp'>>(messages: T[]): T[];
+    private open;
+    private waitToOpen;
+    private makeSender;
+    private show;
+    private showRows;
+    private setStatus;
+}

package/dist/events.d.ts

@@ -0,0 +1,80 @@
+import type { FeedStatus, SkipReason } from './follower.js';
+import type { ChatMessage, FeedEntry, HistoryRow, MessageType } from './message/index.js';
+export declare const EVENTS: {
+    /** `true` when opening starts, `false` once the chat is open and being followed. */
+    readonly LOADING_INIT: 'loadingInit';
+    /** `true` while "load older" reads a history file, then `false`. */
+    readonly LOADING_PREVIOUS_MESSAGES: 'loadingPreviousMessages';
+    /** A message the chat feed shows, a MessageData. Also how the sender learns its message went out. */
+    readonly MESSAGE_RECEIVED: 'messageReceived';
+    /** A message built, signed and about to be written, a MessageData with index -1. */
+    readonly MESSAGE_REQUEST_INITIATED: 'messageRequestInitiated';
+    /** The first write of a message that the node accepted. It is still pending until MESSAGE_RECEIVED. */
+    readonly MESSAGE_REQUEST_UPLOADED: 'messageRequestUploaded';
+    /**
+     * A message whose resends ran out unseen while the reader was live. `retrySendMessage` sends it again. A
+     * MESSAGE_RECEIVED for the same id may still follow, if the server published it late.
+     */
+    readonly MESSAGE_REQUEST_ERROR: 'messageRequestError';
+    /** Opening has failed three times in a row. It keeps trying, and a later LOADING_INIT `false` means it got through. */
+    readonly CRITICAL_ERROR: 'criticalError';
+    /** The reader's state, a FeedStatus: live, reconnecting or stalled. */
+    readonly STATUS: 'status';
+    /** A feed slot or history row not shown, a SkippedMessage. */
+    readonly MESSAGE_SKIPPED: 'messageSkipped';
+    /** Any failure the chat recovers from on its own, for logging. */
+    readonly ERROR: 'error';
+};
+export type ChatEvent = (typeof EVENTS)[keyof typeof EVENTS];
+/** A message as the viewer shows it. The field names are 6.x's, so a viewer built on 6.x changes little. */
+export interface MessageData {
+    id: string;
+    type: MessageType;
+    /** The text, or the emoji of a reaction. */
+    message: string;
+    username: string;
+    address: string;
+    /** The server's receive time once published, the sender's clock while pending. What the viewer shows and sorts by. */
+    timestamp: number;
+    /** The message a thread reply or a reaction refers to. */
+    targetMessageId?: string;
+    chatTopic: string;
+    signature: string;
+    /** The message's place in the chat, its feed index, or -1 while it is pending. */
+    index: number;
+    /** The sender's own clock, which nothing checks. */
+    sentAt: number;
+}
+export interface SkippedMessage {
+    /** The feed index, or -1 for rows of a history file. */
+    index: number;
+    reason: SkipReason | 'history-row';
+    detail: string;
+}
+export declare function pendingMessageData(message: ChatMessage): MessageData;
+export declare function publishedMessageData(entry: FeedEntry | HistoryRow): MessageData;
+export interface ChatEventPayloads {
+    [EVENTS.LOADING_INIT]: boolean;
+    [EVENTS.LOADING_PREVIOUS_MESSAGES]: boolean;
+    [EVENTS.MESSAGE_RECEIVED]: MessageData;
+    [EVENTS.MESSAGE_REQUEST_INITIATED]: MessageData;
+    [EVENTS.MESSAGE_REQUEST_UPLOADED]: MessageData;
+    [EVENTS.MESSAGE_REQUEST_ERROR]: MessageData;
+    [EVENTS.CRITICAL_ERROR]: unknown;
+    [EVENTS.STATUS]: FeedStatus;
+    [EVENTS.MESSAGE_SKIPPED]: SkippedMessage;
+    [EVENTS.ERROR]: unknown;
+}
+type Listener<T> = (data: T) => void;
+/**
+ * The chat's events. `on` and `off` are bound, so a caller may take them apart from the emitter. A listener that
+ * throws is reported on the console and never stops the listeners after it or the chat behind it.
+ */
+export declare class ChatEmitter {
+    private readonly listeners;
+    on: <E extends ChatEvent>(event: E, listener: Listener<ChatEventPayloads[E]>) => void;
+    off: <E extends ChatEvent>(event: E, listener: Listener<ChatEventPayloads[E]>) => void;
+    cleanAll: () => void;
+    emit<E extends ChatEvent>(event: E, data: ChatEventPayloads[E]): void;
+}
+export {};