@foony/chat 0.0.1

package/lib-cjs/rooms.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Room registry. Mirrors `Realtime.channels` — `get(name)` returns a stable
+ * {@link Room} per name (creating its `chat:<name>` channel on first use), and
+ * `release(name)` detaches and drops it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rooms = void 0;
+const protocol_js_1 = require("./protocol.js");
+const room_js_1 = require("./room.js");
+/** Factory and cache for {@link Room} instances on a {@link ChatClient}. */
+class Rooms {
+    realtime;
+    getClientId;
+    byName = new Map();
+    constructor(realtime, getClientId) {
+        this.realtime = realtime;
+        this.getClientId = getClientId;
+    }
+    /** Get (or create) the room named `name`. Stable instance per name. */
+    get(name, options) {
+        let existing = this.byName.get(name);
+        if (!existing) {
+            const channel = this.realtime.channels.get((0, protocol_js_1.roomChannelName)(name));
+            existing = new room_js_1.Room(name, channel, this.getClientId, options);
+            this.byName.set(name, existing);
+        }
+        return existing;
+    }
+    /** Detach and forget the room named `name`. No-op if not present. */
+    release(name) {
+        const room = this.byName.get(name);
+        if (!room) {
+            return;
+        }
+        this.byName.delete(name);
+        room.detach().catch(() => { });
+        this.realtime.channels.release((0, protocol_js_1.roomChannelName)(name));
+    }
+}
+exports.Rooms = Rooms;
+//# sourceMappingURL=rooms.js.map

package/lib-cjs/rooms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rooms.js","sourceRoot":"","sources":["../src/rooms.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAGH,+CAAgD;AAChD,uCAAiC;AAGjC,4EAA4E;AAC5E,MAAa,KAAK;IAIG;IACA;IAJF,MAAM,GAAG,IAAI,GAAG,EAAgB,CAAC;IAElD,YACmB,QAAkB,EAClB,WAAgC;QADhC,aAAQ,GAAR,QAAQ,CAAU;QAClB,gBAAW,GAAX,WAAW,CAAqB;IAChD,CAAC;IAEJ,uEAAuE;IACvE,GAAG,CAAC,IAAY,EAAE,OAAqB;QACrC,IAAI,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAA,6BAAe,EAAC,IAAI,CAAC,CAAC,CAAC;YAClE,QAAQ,GAAG,IAAI,cAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;YAC9D,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,qEAAqE;IACrE,OAAO,CAAC,IAAY;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO;QACT,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzB,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QAC9B,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAA,6BAAe,EAAC,IAAI,CAAC,CAAC,CAAC;IACxD,CAAC;CACF;AA7BD,sBA6BC"}

package/lib-cjs/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Public types for the @foony/chat API.
+ *
+ * Foony-native shapes inspired by Ably Chat: a {@link Message} is keyed by a
+ * stable `id` (so edit/delete reference it directly), and presence/typing/
+ * reactions/occupancy mirror the concepts without copying Ably's exact names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib-cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/lib-cjs/typing.js

@@ -0,0 +1,112 @@
+"use strict";
+/**
+ * Per-room typing indicators — ephemeral, pure client-side logic over the
+ * channel's pub/sub (no persistence, no edge support needed).
+ *
+ * Sender: the first `keystroke()` broadcasts `started` immediately; further
+ * keystrokes within `heartbeatThrottleMs` are no-ops, and one after the window
+ * re-broadcasts. `stop()` broadcasts `stopped`. As long as a client keeps
+ * typing it keeps heartbeating; when it stops, receivers expire it.
+ *
+ * Receiver: tracks who is typing and auto-expires a typer after
+ * `heartbeatThrottleMs + GRACE_MS` with no heartbeat, emitting a synthetic
+ * `stopped`. The local client is excluded from the typing set.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Typing = void 0;
+const protocol_js_1 = require("./protocol.js");
+/** Default heartbeat throttle; must be uniform across clients in a room. */
+const DEFAULT_HEARTBEAT_THROTTLE_MS = 10_000;
+/** Extra time a receiver waits past the throttle before expiring a typer. */
+const GRACE_MS = 2_000;
+/** The typing feature of a {@link Room}. */
+class Typing {
+    channel;
+    getClientId;
+    heartbeatThrottleMs;
+    listeners = new Set();
+    /** Active typers (excluding self) → expiry timer. */
+    typers = new Map();
+    /** When the local client last broadcast a heartbeat; -Infinity means "never / send next". */
+    lastSentAt = Number.NEGATIVE_INFINITY;
+    channelUnsubscribe = null;
+    constructor(channel, getClientId, heartbeatThrottleMs) {
+        this.channel = channel;
+        this.getClientId = getClientId;
+        this.heartbeatThrottleMs = heartbeatThrottleMs ?? DEFAULT_HEARTBEAT_THROTTLE_MS;
+    }
+    /** Signal the local client is typing. Throttled to one heartbeat per window. */
+    async keystroke() {
+        const now = Date.now();
+        if (now - this.lastSentAt < this.heartbeatThrottleMs) {
+            return;
+        }
+        this.lastSentAt = now;
+        const payload = { state: 'started' };
+        await this.channel.publish(protocol_js_1.TYPING_EVENT, payload);
+    }
+    /** Signal the local client has stopped typing. */
+    async stop() {
+        this.lastSentAt = Number.NEGATIVE_INFINITY;
+        const payload = { state: 'stopped' };
+        await this.channel.publish(protocol_js_1.TYPING_EVENT, payload);
+    }
+    /** Client ids currently typing (excludes the local client). */
+    get currentlyTyping() {
+        return new Set(this.typers.keys());
+    }
+    /** Subscribe to typing changes. Attaches the channel on first listener. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        this.ensureChannelSubscription();
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    ensureChannelSubscription() {
+        if (this.channelUnsubscribe) {
+            return;
+        }
+        this.channelUnsubscribe = this.channel.subscribe(protocol_js_1.TYPING_EVENT, (frame) => {
+            const payload = (0, protocol_js_1.parseTypingPayload)(frame.data);
+            const clientId = frame.clientId;
+            if (payload === null || clientId === undefined || clientId === this.getClientId()) {
+                return;
+            }
+            if (payload.state === 'started') {
+                this.markTyping(clientId);
+            }
+            else {
+                this.markStopped(clientId);
+            }
+        });
+    }
+    markTyping(clientId) {
+        const existing = this.typers.get(clientId);
+        if (existing) {
+            clearTimeout(existing);
+        }
+        const timer = setTimeout(() => this.markStopped(clientId), this.heartbeatThrottleMs + GRACE_MS);
+        this.typers.set(clientId, timer);
+        if (!existing) {
+            this.emit({ type: 'started', clientId });
+        }
+    }
+    markStopped(clientId) {
+        const existing = this.typers.get(clientId);
+        if (!existing) {
+            return;
+        }
+        clearTimeout(existing);
+        this.typers.delete(clientId);
+        this.emit({ type: 'stopped', clientId });
+    }
+    emit(change) {
+        const event = { currentlyTyping: new Set(this.typers.keys()), change };
+        for (const listener of [...this.listeners]) {
+            listener(event);
+        }
+    }
+}
+exports.Typing = Typing;
+//# sourceMappingURL=typing.js.map

package/lib-cjs/typing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typing.js","sourceRoot":"","sources":["../src/typing.ts"],"names":[],"mappings":"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"}

package/lib-cjs/util.js

@@ -0,0 +1,15 @@
+"use strict";
+/** Small internal helpers shared across chat features. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newMessageId = newMessageId;
+/**
+ * A sender-assigned, roughly time-sortable message id: `<unixMillis>-<random>`.
+ * Mirrors the realtime SDK's transport id format, but the chat id is decoupled
+ * from transport — it lives in the payload so `send` can return it immediately
+ * and `update`/`delete` can reference it.
+ */
+function newMessageId() {
+    const random = Math.floor(Math.random() * 0x1_0000_0000).toString(16).padStart(8, '0');
+    return `${Date.now()}-${random}`;
+}
+//# sourceMappingURL=util.js.map

package/lib-cjs/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":";AAAA,0DAA0D;;AAQ1D,oCAGC;AATD;;;;;GAKG;AACH,SAAgB,YAAY;IAC1B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACvF,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,MAAM,EAAE,CAAC;AACnC,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@foony/chat",
+  "version": "0.0.1",
+  "description": "Chat API (rooms, messages, typing, reactions, presence, occupancy) built on @foony/realtime.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Foony-Limited/chat-js.git"
+  },
+  "keywords": [
+    "foony",
+    "chat",
+    "realtime",
+    "websocket",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./lib-cjs/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "lib-cjs",
+    "lib",
+    "src/**/*.ts",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib-cjs/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package-json.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@foony/realtime": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@foony/realtime": "file:../realtime-js",
+    "@types/node": "^22.13.0",
+    "typescript": "6.0.3",
+    "vitest": "^4.0.14"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/chatClient.ts

@@ -0,0 +1,31 @@
+/**
+ * ChatClient is the top-level entry point: wrap a connected (or connecting)
+ * {@link Realtime} client and use `chat.rooms.get(name)` to start chatting.
+ * The chat layer adds no new transport — it rides the existing connection.
+ */
+
+import type { Connection, Realtime } from '@foony/realtime';
+import { Rooms } from './rooms.js';
+
+/** Chat client built on top of a {@link Realtime} instance. */
+export class ChatClient {
+  /** Room registry and factory. */
+  readonly rooms: Rooms;
+
+  constructor(private readonly realtime: Realtime) {
+    this.rooms = new Rooms(realtime, () => this.clientId);
+  }
+
+  /** The underlying realtime connection (status, events). */
+  get connection(): Connection {
+    return this.realtime.connection;
+  }
+
+  /**
+   * The resolved client id for this connection, or null until the auth
+   * handshake completes. Used to attribute messages and detect self.
+   */
+  get clientId(): string | null {
+    return this.realtime.getClientId();
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * Public entry point for @foony/chat.
+ *
+ * A chat layer over @foony/realtime: construct a `ChatClient` from a `Realtime`
+ * instance, then `chat.rooms.get(name)` for messages, presence, typing,
+ * reactions and occupancy. React bindings are intentionally out of this core
+ * package (planned as a separate `@foony/chat/react` subpath).
+ */
+
+export { ChatClient } from './chatClient.js';
+export { Rooms } from './rooms.js';
+export { Room, type RoomStatus, type DiscontinuityListener } from './room.js';
+export { Messages, type MessageListener } from './messages.js';
+export { Presence, type PresenceListener } from './presence.js';
+export { Typing, type TypingListener } from './typing.js';
+export { Reactions, type ReactionListener } from './reactions.js';
+export { Occupancy, type OccupancyListener } from './occupancy.js';
+export { MessageReconciler } from './reconciler.js';
+export type {
+  Message,
+  MessageAction,
+  ChatMessageEvent,
+  SendMessageParams,
+  UpdateMessageParams,
+  MessagePage,
+  PresenceMember,
+  PresenceEvent,
+  TypingEvent,
+  RoomReaction,
+  Occupancy as OccupancyData,
+  RoomOptions,
+} from './types.js';

package/src/messages.ts

@@ -0,0 +1,159 @@
+/**
+ * Per-room message API: send, edit, delete, subscribe, and history.
+ *
+ * One {@link MessageReconciler} is shared across every subscriber and the
+ * history backfill, so live and replayed frames converge on identical state.
+ * Subscribers see only live frames; history is returned as a separate page
+ * (the app renders backfill itself, matching Ably's historyBeforeSubscribe).
+ */
+
+import type { Channel, MessageFrame, UnsubscribeFn } from '@foony/realtime';
+import { MESSAGE_EVENT, PAYLOAD_VERSION, type MessagePayload } from './protocol.js';
+import { MessageReconciler } from './reconciler.js';
+import type { ChatMessageEvent, Message, MessagePage, SendMessageParams, UpdateMessageParams } from './types.js';
+import { newMessageId } from './util.js';
+
+/** Listener invoked for every materialized message change on the room. */
+export type MessageListener = (event: ChatMessageEvent) => void;
+
+/**
+ * Retention requested for chat messages: the maximum the platform offers (1
+ * year). The edge clamps this down to the app's plan ceiling, so a chat message
+ * persists as long as the plan allows — versus typing/reactions, which are left
+ * at the short ephemeral default. One year in milliseconds.
+ */
+const MESSAGE_TTL_MS = 365 * 24 * 60 * 60 * 1000;
+
+/** The message feature of a {@link Room}. */
+export class Messages {
+  private readonly reconciler: MessageReconciler;
+  private readonly listeners = new Set<MessageListener>();
+  private channelUnsubscribe: UnsubscribeFn | null = null;
+
+  constructor(
+    private readonly channel: Channel,
+    private readonly roomName: string,
+    private readonly getClientId: () => string | null,
+  ) {
+    this.reconciler = new MessageReconciler(roomName);
+  }
+
+  /** Send a new message. Returns the message optimistically; its `id` is stable. */
+  async send(params: SendMessageParams): Promise<Message> {
+    const id = newMessageId();
+    const payload: MessagePayload = {
+      v: PAYLOAD_VERSION,
+      action: 'create',
+      id,
+      text: params.text,
+      ...(params.metadata === undefined ? {} : { metadata: params.metadata }),
+      ...(params.headers === undefined ? {} : { headers: params.headers }),
+    };
+    await this.channel.publish(MESSAGE_EVENT, payload, { ttlMs: MESSAGE_TTL_MS });
+    const now = new Date();
+    return {
+      id,
+      clientId: this.getClientId() ?? '',
+      roomName: this.roomName,
+      text: params.text,
+      metadata: params.metadata ?? {},
+      headers: params.headers ?? {},
+      createdAt: now,
+      updatedAt: now,
+      action: 'create',
+      deleted: false,
+    };
+  }
+
+  /** Edit a message by id. Replaces text/metadata/headers (omitted fields clear). */
+  async update(id: string, params: UpdateMessageParams): Promise<void> {
+    const payload: MessagePayload = {
+      v: PAYLOAD_VERSION,
+      action: 'update',
+      id,
+      text: params.text,
+      ...(params.metadata === undefined ? {} : { metadata: params.metadata }),
+      ...(params.headers === undefined ? {} : { headers: params.headers }),
+    };
+    await this.channel.publish(MESSAGE_EVENT, payload, { ttlMs: MESSAGE_TTL_MS });
+  }
+
+  /** Delete a message by id. */
+  async delete(id: string): Promise<void> {
+    const payload: MessagePayload = { v: PAYLOAD_VERSION, action: 'delete', id };
+    await this.channel.publish(MESSAGE_EVENT, payload, { ttlMs: MESSAGE_TTL_MS });
+  }
+
+  /**
+   * Subscribe to live message changes. The first subscriber attaches the
+   * underlying channel subscription; the last to unsubscribe removes it.
+   */
+  subscribe(listener: MessageListener): UnsubscribeFn {
+    this.listeners.add(listener);
+    this.ensureChannelSubscription();
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0 && this.channelUnsubscribe) {
+        this.channelUnsubscribe();
+        this.channelUnsubscribe = null;
+      }
+    };
+  }
+
+  /**
+   * Fetch a page of past messages, oldest-first, materialized through the same
+   * reconciler as the live stream. Pass `cursor` (a previous page's
+   * `nextCursor`) to page further back.
+   */
+  async history(params?: { limit?: number; cursor?: string }): Promise<MessagePage> {
+    const { messages: frames, more } = await this.channel.history({
+      ...(params?.limit === undefined ? {} : { limit: params.limit }),
+      ...(params?.cursor === undefined ? {} : { start: params.cursor }),
+    });
+    const touched: string[] = [];
+    for (const frame of frames) {
+      if (frame.name !== MESSAGE_EVENT) {
+        continue;
+      }
+      this.reconciler.apply(frame);
+      const id = messageIdOf(frame);
+      if (id !== null && !touched.includes(id)) {
+        touched.push(id);
+      }
+    }
+    const messages = touched
+      .map((id) => this.reconciler.get(id))
+      .filter((message): message is Message => message !== undefined);
+    return {
+      messages,
+      hasMore: more,
+      ...(frames.length > 0 && frames[0] ? { nextCursor: frames[0].messageId } : {}),
+    };
+  }
+
+  /** Lazily attach the single channel subscription that feeds the reconciler. */
+  private ensureChannelSubscription(): void {
+    if (this.channelUnsubscribe) {
+      return;
+    }
+    this.channelUnsubscribe = this.channel.subscribe(MESSAGE_EVENT, (frame) => {
+      const event = this.reconciler.apply(frame);
+      if (event === null) {
+        return;
+      }
+      for (const listener of [...this.listeners]) {
+        listener(event);
+      }
+    });
+  }
+}
+
+/** The chat message id a frame refers to (payload `id`), or null if unparseable. */
+function messageIdOf(frame: MessageFrame): string | null {
+  const data = frame.data;
+  if (typeof data !== 'object' || data === null) {
+    return null;
+  }
+  const id = (data as Record<string, unknown>)['id'];
+  return typeof id === 'string' && id !== '' ? id : null;
+}

package/src/occupancy.ts

@@ -0,0 +1,78 @@
+/**
+ * Per-room occupancy, derived entirely from the presence set — no edge call.
+ *
+ * `connections` counts distinct (clientId, connectionId) pairs present (a user
+ * on two devices = two connections); `presenceMembers` counts distinct client
+ * ids. This reuses presence's TTL-based ghost-leave detection, so counts
+ * self-heal after a crash. Limitation: it only counts members who entered
+ * presence — always the case in a chat room, where joining enters presence.
+ */
+
+import type { UnsubscribeFn } from '@foony/realtime';
+import type { Presence } from './presence.js';
+import type { Occupancy as OccupancyData } from './types.js';
+
+/** Listener invoked when occupancy counts change. */
+export type OccupancyListener = (occupancy: OccupancyData) => void;
+
+/** Default debounce for occupancy change events. */
+const DEFAULT_DEBOUNCE_MS = 1_000;
+
+/** The occupancy feature of a {@link Room}. */
+export class Occupancy {
+  private readonly listeners = new Set<OccupancyListener>();
+  private readonly debounceMs: number;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastEmitted: OccupancyData | null = null;
+  private membersChangedUnsubscribe: UnsubscribeFn | null = null;
+
+  constructor(
+    private readonly presence: Presence,
+    debounceMs?: number,
+  ) {
+    this.debounceMs = debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  }
+
+  /** Current occupancy snapshot, computed from the local presence member set. */
+  get(): OccupancyData {
+    const members = this.presence.get();
+    const clientIds = new Set(members.map((member) => member.clientId));
+    return { connections: members.length, presenceMembers: clientIds.size };
+  }
+
+  /** Subscribe to occupancy changes (debounced, deduplicated). */
+  subscribe(listener: OccupancyListener): UnsubscribeFn {
+    this.listeners.add(listener);
+    if (!this.membersChangedUnsubscribe) {
+      this.membersChangedUnsubscribe = this.presence.onMembersChanged(() => this.scheduleEmit());
+    }
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0 && this.membersChangedUnsubscribe) {
+        this.membersChangedUnsubscribe();
+        this.membersChangedUnsubscribe = null;
+        if (this.debounceTimer) {
+          clearTimeout(this.debounceTimer);
+          this.debounceTimer = null;
+        }
+      }
+    };
+  }
+
+  private scheduleEmit(): void {
+    if (this.debounceTimer) {
+      return;
+    }
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      const current = this.get();
+      if (this.lastEmitted && this.lastEmitted.connections === current.connections && this.lastEmitted.presenceMembers === current.presenceMembers) {
+        return;
+      }
+      this.lastEmitted = current;
+      for (const listener of [...this.listeners]) {
+        listener(current);
+      }
+    }, this.debounceMs);
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,90 @@
+/**
+ * Internal wire conventions for the chat layer: the reserved `name` values
+ * used on the underlying realtime channel and the JSON payload shapes carried
+ * in each. Not part of the public API — kept in one place so producers and the
+ * reconciler agree.
+ */
+
+/** Channel name for a room. The edge grammar forbids `$`, so we namespace with `:`. */
+export function roomChannelName(roomName: string): string {
+  return `chat:${roomName}`;
+}
+
+/** Event name carrying message create/update/delete payloads. */
+export const MESSAGE_EVENT = 'chat.message';
+/** Event name carrying ephemeral room-level reactions. */
+export const REACTION_EVENT = 'chat.reaction';
+/** Event name carrying ephemeral typing heartbeats and stops. */
+export const TYPING_EVENT = 'chat.typing';
+
+/** Payload schema version, bumped if the on-channel shape ever changes. */
+export const PAYLOAD_VERSION = 1;
+
+/** Payload published under {@link MESSAGE_EVENT}. `id` is the message id in all actions. */
+export type MessagePayload =
+  | { readonly v: number; readonly action: 'create'; readonly id: string; readonly text: string; readonly metadata?: Record<string, unknown>; readonly headers?: Record<string, unknown> }
+  | { readonly v: number; readonly action: 'update'; readonly id: string; readonly text: string; readonly metadata?: Record<string, unknown>; readonly headers?: Record<string, unknown> }
+  | { readonly v: number; readonly action: 'delete'; readonly id: string };
+
+/** Payload published under {@link TYPING_EVENT}. */
+export type TypingPayload = { readonly state: 'started' | 'stopped' };
+
+/** Payload published under {@link REACTION_EVENT}. */
+export type ReactionPayload = { readonly name: string; readonly metadata?: unknown };
+
+/** Parse an unknown message payload, returning null if it is malformed or a foreign frame. */
+export function parseMessagePayload(data: unknown): MessagePayload | null {
+  if (typeof data !== 'object' || data === null) {
+    return null;
+  }
+  const payload = data as Record<string, unknown>;
+  const action = payload['action'];
+  const id = payload['id'];
+  if (typeof id !== 'string' || id === '') {
+    return null;
+  }
+  if (action === 'delete') {
+    return { v: PAYLOAD_VERSION, action, id };
+  }
+  if ((action === 'create' || action === 'update') && typeof payload['text'] === 'string') {
+    const text = payload['text'] as string;
+    const metadata = isRecord(payload['metadata']) ? (payload['metadata'] as Record<string, unknown>) : undefined;
+    const headers = isRecord(payload['headers']) ? (payload['headers'] as Record<string, unknown>) : undefined;
+    return {
+      v: PAYLOAD_VERSION,
+      action,
+      id,
+      text,
+      ...(metadata === undefined ? {} : { metadata }),
+      ...(headers === undefined ? {} : { headers }),
+    };
+  }
+  return null;
+}
+
+/** Parse an unknown typing payload, returning null if malformed. */
+export function parseTypingPayload(data: unknown): TypingPayload | null {
+  if (typeof data !== 'object' || data === null) {
+    return null;
+  }
+  const state = (data as Record<string, unknown>)['state'];
+  return state === 'started' || state === 'stopped' ? { state } : null;
+}
+
+/** Parse an unknown reaction payload, returning null if malformed. */
+export function parseReactionPayload(data: unknown): ReactionPayload | null {
+  if (typeof data !== 'object' || data === null) {
+    return null;
+  }
+  const name = (data as Record<string, unknown>)['name'];
+  if (typeof name !== 'string' || name === '') {
+    return null;
+  }
+  const metadata = (data as Record<string, unknown>)['metadata'];
+  return metadata === undefined ? { name } : { name, metadata };
+}
+
+/** True when `value` is a non-null, non-array object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}