@foony/chat 0.0.1

package/src/reactions.ts

@@ -0,0 +1,64 @@
+/**
+ * Per-room reactions — ephemeral, fire-and-forget broadcasts (e.g. a floating
+ * emoji). Not stored or aggregated; distinct from per-message reactions (which
+ * are out of scope for v1). Pure pub/sub over the channel.
+ */
+
+import type { Channel, UnsubscribeFn } from '@foony/realtime';
+import { parseReactionPayload, REACTION_EVENT, type ReactionPayload } from './protocol.js';
+import type { RoomReaction } from './types.js';
+
+/** Listener invoked for every room reaction. */
+export type ReactionListener = (reaction: RoomReaction) => void;
+
+/** The room-reaction feature of a {@link Room}. */
+export class Reactions {
+  private readonly listeners = new Set<ReactionListener>();
+  private channelUnsubscribe: UnsubscribeFn | null = null;
+
+  constructor(
+    private readonly channel: Channel,
+    private readonly getClientId: () => string | null,
+  ) {}
+
+  /** Broadcast a room reaction. */
+  async send(params: { name: string; metadata?: unknown }): Promise<void> {
+    const payload: ReactionPayload = {
+      name: params.name,
+      ...(params.metadata === undefined ? {} : { metadata: params.metadata }),
+    };
+    await this.channel.publish(REACTION_EVENT, payload);
+  }
+
+  /** Subscribe to room reactions. Attaches the channel on first listener. */
+  subscribe(listener: ReactionListener): UnsubscribeFn {
+    this.listeners.add(listener);
+    this.ensureChannelSubscription();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private ensureChannelSubscription(): void {
+    if (this.channelUnsubscribe) {
+      return;
+    }
+    this.channelUnsubscribe = this.channel.subscribe(REACTION_EVENT, (frame) => {
+      const payload = parseReactionPayload(frame.data);
+      if (payload === null) {
+        return;
+      }
+      const clientId = frame.clientId ?? '';
+      const reaction: RoomReaction = {
+        name: payload.name,
+        clientId,
+        ...(payload.metadata === undefined ? {} : { metadata: payload.metadata }),
+        createdAt: new Date(frame.timestamp),
+        isSelf: clientId !== '' && clientId === this.getClientId(),
+      };
+      for (const subscriber of [...this.listeners]) {
+        subscriber(reaction);
+      }
+    });
+  }
+}

package/src/reconciler.ts

@@ -0,0 +1,169 @@
+/**
+ * Message reconciler: folds a stream of create/update/delete frames into
+ * materialized {@link Message} state, keyed by message id. The same reconciler
+ * runs over the live subscription and over replayed history, so both paths
+ * converge on identical state regardless of delivery order or duplicates.
+ *
+ * Version ordering uses the transport `(timestamp, messageId)` pair: a later
+ * mutation wins, and a re-delivered frame (same messageId) is ignored.
+ */
+
+import type { MessageFrame } from '@foony/realtime';
+import { parseMessagePayload, type MessagePayload } from './protocol.js';
+import type { ChatMessageEvent, Message } from './types.js';
+
+/** Internal per-message bookkeeping. */
+type Entry = {
+  message: Message;
+  /** True once the original `create` has been folded in. */
+  createSeen: boolean;
+  /** Transport timestamp of the version that set the current text. */
+  versionTs: number;
+  /** Transport messageId of that version. */
+  versionId: string;
+  /** Every transport messageId already applied, for idempotent replay. */
+  readonly applied: Set<string>;
+};
+
+/** Stateful reconciler for a single room's messages. */
+export class MessageReconciler {
+  private readonly byId = new Map<string, Entry>();
+
+  constructor(private readonly roomName: string) {}
+
+  /**
+   * Fold one channel frame into state. Returns the event a subscriber should
+   * see, or null when the frame is malformed, a duplicate, or stale.
+   */
+  apply(frame: MessageFrame): ChatMessageEvent | null {
+    const payload = parseMessagePayload(frame.data);
+    if (payload === null) {
+      return null;
+    }
+    const timestamp = frame.timestamp;
+    const versionId = frame.messageId;
+    if (payload.action === 'create') {
+      return this.applyCreate(payload, frame.clientId ?? '', timestamp, versionId);
+    }
+    return this.applyMutation(payload, frame.clientId ?? '', timestamp, versionId);
+  }
+
+  /** The current materialized state of one message, if known. */
+  get(id: string): Message | undefined {
+    return this.byId.get(id)?.message;
+  }
+
+  /** Current materialized messages, oldest-first by creation then id. */
+  snapshot(): Message[] {
+    return [...this.byId.values()]
+      .map((entry) => entry.message)
+      .sort((left, right) => left.createdAt.getTime() - right.createdAt.getTime() || (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+  }
+
+  private applyCreate(payload: Extract<MessagePayload, { action: 'create' }>, clientId: string, timestamp: number, versionId: string): ChatMessageEvent | null {
+    const existing = this.byId.get(payload.id);
+    if (existing) {
+      if (existing.applied.has(versionId)) {
+        return null;
+      }
+      existing.applied.add(versionId);
+      // A mutation arrived before its create: backfill author/createdAt, and
+      // adopt the create's body only if it is newer than the winning mutation
+      // (i.e. no later edit/delete has superseded it).
+      const createdAt = new Date(timestamp);
+      const adoptBody = isNewer(existing.versionTs, existing.versionId, timestamp, versionId);
+      existing.createSeen = true;
+      existing.message = {
+        ...existing.message,
+        clientId,
+        createdAt,
+        ...(adoptBody
+          ? {
+              text: payload.text,
+              metadata: payload.metadata ?? {},
+              headers: payload.headers ?? {},
+              updatedAt: createdAt,
+              action: 'create',
+              deleted: false,
+            }
+          : {}),
+      };
+      if (adoptBody) {
+        existing.versionTs = timestamp;
+        existing.versionId = versionId;
+      }
+      return { type: 'created', message: existing.message };
+    }
+    const createdAt = new Date(timestamp);
+    const message: Message = {
+      id: payload.id,
+      clientId,
+      roomName: this.roomName,
+      text: payload.text,
+      metadata: payload.metadata ?? {},
+      headers: payload.headers ?? {},
+      createdAt,
+      updatedAt: createdAt,
+      action: 'create',
+      deleted: false,
+    };
+    this.byId.set(payload.id, { message, createSeen: true, versionTs: timestamp, versionId, applied: new Set([versionId]) });
+    return { type: 'created', message };
+  }
+
+  private applyMutation(payload: Extract<MessagePayload, { action: 'update' | 'delete' }>, clientId: string, timestamp: number, versionId: string): ChatMessageEvent | null {
+    let entry = this.byId.get(payload.id);
+    if (!entry) {
+      // Mutation before create: stand up a placeholder the create can complete.
+      const createdAt = new Date(timestamp);
+      const placeholder: Message = {
+        id: payload.id,
+        clientId,
+        roomName: this.roomName,
+        text: '',
+        metadata: {},
+        headers: {},
+        createdAt,
+        updatedAt: createdAt,
+        action: 'create',
+        deleted: false,
+      };
+      entry = { message: placeholder, createSeen: false, versionTs: -1, versionId: '', applied: new Set() };
+      this.byId.set(payload.id, entry);
+    }
+    if (entry.applied.has(versionId)) {
+      return null;
+    }
+    entry.applied.add(versionId);
+    if (!isNewer(entry.versionTs, entry.versionId, timestamp, versionId)) {
+      return null;
+    }
+    const updatedAt = new Date(timestamp);
+    if (payload.action === 'delete') {
+      entry.message = { ...entry.message, text: '', metadata: {}, headers: {}, updatedAt, action: 'delete', deleted: true };
+      entry.versionTs = timestamp;
+      entry.versionId = versionId;
+      return { type: 'deleted', message: entry.message };
+    }
+    entry.message = {
+      ...entry.message,
+      text: payload.text,
+      metadata: payload.metadata ?? {},
+      headers: payload.headers ?? {},
+      updatedAt,
+      action: 'update',
+      deleted: false,
+    };
+    entry.versionTs = timestamp;
+    entry.versionId = versionId;
+    return { type: 'updated', message: entry.message };
+  }
+}
+
+/** True when `(ts, id)` is strictly newer than `(priorTs, priorId)`. */
+function isNewer(priorTs: number, priorId: string, ts: number, id: string): boolean {
+  if (ts !== priorTs) {
+    return ts > priorTs;
+  }
+  return id > priorId;
+}

package/src/room.ts

@@ -0,0 +1,97 @@
+/**
+ * A chat room: one realtime channel (`chat:<name>`) carrying messages,
+ * presence, typing, reactions and occupancy. Lifecycle (`attach`/`detach`/
+ * status) delegates to the underlying channel rather than duplicating a state
+ * machine.
+ */
+
+import type { Channel, ChannelStateChange, UnsubscribeFn } from '@foony/realtime';
+import { Messages } from './messages.js';
+import { Occupancy } from './occupancy.js';
+import { Presence } from './presence.js';
+import { Reactions } from './reactions.js';
+import { Typing } from './typing.js';
+import type { RoomOptions } from './types.js';
+
+/** Room lifecycle status — the underlying channel's state. */
+export type RoomStatus = Channel['state'];
+
+/** Listener invoked when a continuity gap is detected on (re)attach. */
+export type DiscontinuityListener = (reason?: Error) => void;
+
+/** A chat room and its features. Obtain via `chatClient.rooms.get(name)`. */
+export class Room {
+  /** Messages: send, edit, delete, subscribe, history. */
+  readonly messages: Messages;
+  /** Presence: enter/update/leave plus a local member snapshot. */
+  readonly presence: Presence;
+  /** Typing indicators. */
+  readonly typing: Typing;
+  /** Ephemeral room-level reactions. */
+  readonly reactions: Reactions;
+  /** Occupancy counts derived from presence. */
+  readonly occupancy: Occupancy;
+
+  private readonly discontinuityListeners = new Set<DiscontinuityListener>();
+  private hadBeenAttached = false;
+
+  constructor(
+    /** Room name (without the `chat:` channel prefix). */
+    readonly name: string,
+    private readonly channel: Channel,
+    getClientId: () => string | null,
+    options?: RoomOptions,
+  ) {
+    this.messages = new Messages(channel, name, getClientId);
+    this.presence = new Presence(channel);
+    this.typing = new Typing(channel, getClientId, options?.typing?.heartbeatThrottleMs);
+    this.reactions = new Reactions(channel, getClientId);
+    this.occupancy = new Occupancy(this.presence, options?.occupancy?.debounceMs);
+    channel.on((change) => this.onChannelState(change));
+  }
+
+  /** Current room status. */
+  get status(): RoomStatus {
+    return this.channel.state;
+  }
+
+  /** Ensure the room is attached so messages and presence flow. */
+  async attach(): Promise<void> {
+    await this.channel.attach();
+  }
+
+  /** Detach from the room (stop receiving). Listeners are preserved. */
+  async detach(): Promise<void> {
+    await this.channel.detach();
+  }
+
+  /** Subscribe to room status changes. Returns an unsubscribe function. */
+  onStatusChange(listener: (change: ChannelStateChange) => void): UnsubscribeFn {
+    return this.channel.on(listener);
+  }
+
+  /**
+   * Subscribe to continuity gaps — best-effort: fires when the room re-attaches
+   * without a resume, so the app can backfill via `messages.history()`.
+   */
+  onDiscontinuity(listener: DiscontinuityListener): UnsubscribeFn {
+    this.discontinuityListeners.add(listener);
+    return () => {
+      this.discontinuityListeners.delete(listener);
+    };
+  }
+
+  private onChannelState(change: ChannelStateChange): void {
+    if (change.current === 'attached') {
+      if (this.hadBeenAttached && !change.resumed) {
+        for (const listener of [...this.discontinuityListeners]) {
+          listener(change.reason);
+        }
+      }
+      this.hadBeenAttached = true;
+    } else if (change.current === 'detached') {
+      // A deliberate detach/re-attach is not a continuity gap.
+      this.hadBeenAttached = false;
+    }
+  }
+}

package/src/rooms.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+
+import type { Realtime } from '@foony/realtime';
+import { roomChannelName } from './protocol.js';
+import { Room } from './room.js';
+import type { RoomOptions } from './types.js';
+
+/** Factory and cache for {@link Room} instances on a {@link ChatClient}. */
+export class Rooms {
+  private readonly byName = new Map<string, Room>();
+
+  constructor(
+    private readonly realtime: Realtime,
+    private readonly getClientId: () => string | null,
+  ) {}
+
+  /** Get (or create) the room named `name`. Stable instance per name. */
+  get(name: string, options?: RoomOptions): Room {
+    let existing = this.byName.get(name);
+    if (!existing) {
+      const channel = this.realtime.channels.get(roomChannelName(name));
+      existing = new 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: string): void {
+    const room = this.byName.get(name);
+    if (!room) {
+      return;
+    }
+    this.byName.delete(name);
+    room.detach().catch(() => {});
+    this.realtime.channels.release(roomChannelName(name));
+  }
+}

package/src/types.ts

@@ -0,0 +1,141 @@
+/**
+ * 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.
+ */
+
+/** Latest action that produced a message's current state. */
+export type MessageAction = 'create' | 'update' | 'delete';
+
+/**
+ * A materialized chat message. Edits replace `text`/`metadata`/`headers`;
+ * deletes blank them and set {@link Message.deleted}. Reconcile by `id`.
+ */
+export type Message = {
+  /** Stable, sender-assigned message id. Pass it to `update`/`delete`. */
+  readonly id: string;
+  /** Client id of the author. */
+  readonly clientId: string;
+  /** Room this message belongs to. */
+  readonly roomName: string;
+  /** Message body; `''` once the message is deleted. */
+  readonly text: string;
+  /** Arbitrary application metadata; `{}` once deleted. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+  /** Arbitrary application headers; `{}` once deleted. */
+  readonly headers: Readonly<Record<string, unknown>>;
+  /** When the message was created (server publish time). */
+  readonly createdAt: Date;
+  /** When the message last changed; equals `createdAt` until edited or deleted. */
+  readonly updatedAt: Date;
+  /** The latest applied action. */
+  readonly action: MessageAction;
+  /** True once a delete has been applied. */
+  readonly deleted: boolean;
+};
+
+/** Event delivered to message subscribers as the room's history materializes. */
+export type ChatMessageEvent =
+  | { readonly type: 'created'; readonly message: Message }
+  | { readonly type: 'updated'; readonly message: Message }
+  | { readonly type: 'deleted'; readonly message: Message };
+
+/** Fields a caller may set when sending a new message. */
+export type SendMessageParams = {
+  /** Message body. */
+  readonly text: string;
+  /** Optional application metadata. */
+  readonly metadata?: Record<string, unknown>;
+  /** Optional application headers. */
+  readonly headers?: Record<string, unknown>;
+};
+
+/** Fields a caller may change when editing a message. Omitted fields are cleared. */
+export type UpdateMessageParams = {
+  /** New message body. */
+  readonly text: string;
+  /** Replacement metadata (defaults to `{}`). */
+  readonly metadata?: Record<string, unknown>;
+  /** Replacement headers (defaults to `{}`). */
+  readonly headers?: Record<string, unknown>;
+};
+
+/** A page of materialized messages returned by `messages.history`. */
+export type MessagePage = {
+  /** Messages in the page, oldest-first. */
+  readonly messages: readonly Message[];
+  /** True when older messages remain beyond this page. */
+  readonly hasMore: boolean;
+  /** Cursor (oldest message id in the page) to pass back for the next page. */
+  readonly nextCursor?: string;
+};
+
+/** A single presence member in a room. */
+export type PresenceMember = {
+  /** Member's client id. */
+  readonly clientId: string;
+  /** Member's connection id (a user on two devices appears as two members). */
+  readonly connectionId: string;
+  /** Presence payload supplied on enter/update, if any. */
+  readonly data?: unknown;
+  /** When this member's presence last changed. */
+  readonly updatedAt: Date;
+};
+
+/** Normalized presence transition delivered to presence subscribers. */
+export type PresenceEvent = {
+  /** Which transition occurred. */
+  readonly type: 'enter' | 'update' | 'leave';
+  /** The member the transition is about. */
+  readonly member: PresenceMember;
+};
+
+/** Snapshot of who is currently typing in a room (excludes the local client). */
+export type TypingEvent = {
+  /** Client ids currently typing. */
+  readonly currentlyTyping: ReadonlySet<string>;
+  /** The change that produced this event. */
+  readonly change: { readonly type: 'started' | 'stopped'; readonly clientId: string };
+};
+
+/** An ephemeral, room-level reaction (fire-and-forget; not stored). */
+export type RoomReaction = {
+  /** Reaction name, e.g. an emoji or short code. */
+  readonly name: string;
+  /** Client id that sent the reaction. */
+  readonly clientId: string;
+  /** Optional reaction metadata. */
+  readonly metadata?: unknown;
+  /** When the reaction was sent (server publish time). */
+  readonly createdAt: Date;
+  /** True when the local client sent this reaction. */
+  readonly isSelf: boolean;
+};
+
+/** Room occupancy counts derived from the presence set. */
+export type Occupancy = {
+  /** Distinct (clientId, connectionId) pairs present — i.e. connections in presence. */
+  readonly connections: number;
+  /** Distinct client ids present. */
+  readonly presenceMembers: number;
+};
+
+/** Per-room configuration. */
+export type RoomOptions = {
+  /** Typing config. */
+  readonly typing?: {
+    /**
+     * How often a continuously-typing client re-broadcasts that it is typing,
+     * and the basis for receiver-side expiry. Must be uniform across clients
+     * in a room. Defaults to 10000ms.
+     */
+    readonly heartbeatThrottleMs?: number;
+  };
+  /** Occupancy config. */
+  readonly occupancy?: {
+    /** Debounce window for occupancy change events. Defaults to 1000ms. */
+    readonly debounceMs?: number;
+  };
+};

package/src/typing.ts

@@ -0,0 +1,123 @@
+/**
+ * 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.
+ */
+
+import type { Channel, UnsubscribeFn } from '@foony/realtime';
+import { parseTypingPayload, TYPING_EVENT, type TypingPayload } from './protocol.js';
+import type { TypingEvent } from './types.js';
+
+/** Listener invoked whenever the set of typers changes. */
+export type TypingListener = (event: TypingEvent) => void;
+
+/** 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}. */
+export class Typing {
+  private readonly heartbeatThrottleMs: number;
+  private readonly listeners = new Set<TypingListener>();
+  /** Active typers (excluding self) → expiry timer. */
+  private readonly typers = new Map<string, ReturnType<typeof setTimeout>>();
+  /** When the local client last broadcast a heartbeat; -Infinity means "never / send next". */
+  private lastSentAt = Number.NEGATIVE_INFINITY;
+  private channelUnsubscribe: UnsubscribeFn | null = null;
+
+  constructor(
+    private readonly channel: Channel,
+    private readonly getClientId: () => string | null,
+    heartbeatThrottleMs?: number,
+  ) {
+    this.heartbeatThrottleMs = heartbeatThrottleMs ?? DEFAULT_HEARTBEAT_THROTTLE_MS;
+  }
+
+  /** Signal the local client is typing. Throttled to one heartbeat per window. */
+  async keystroke(): Promise<void> {
+    const now = Date.now();
+    if (now - this.lastSentAt < this.heartbeatThrottleMs) {
+      return;
+    }
+    this.lastSentAt = now;
+    const payload: TypingPayload = { state: 'started' };
+    await this.channel.publish(TYPING_EVENT, payload);
+  }
+
+  /** Signal the local client has stopped typing. */
+  async stop(): Promise<void> {
+    this.lastSentAt = Number.NEGATIVE_INFINITY;
+    const payload: TypingPayload = { state: 'stopped' };
+    await this.channel.publish(TYPING_EVENT, payload);
+  }
+
+  /** Client ids currently typing (excludes the local client). */
+  get currentlyTyping(): ReadonlySet<string> {
+    return new Set(this.typers.keys());
+  }
+
+  /** Subscribe to typing changes. Attaches the channel on first listener. */
+  subscribe(listener: TypingListener): UnsubscribeFn {
+    this.listeners.add(listener);
+    this.ensureChannelSubscription();
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  private ensureChannelSubscription(): void {
+    if (this.channelUnsubscribe) {
+      return;
+    }
+    this.channelUnsubscribe = this.channel.subscribe(TYPING_EVENT, (frame) => {
+      const payload = 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);
+      }
+    });
+  }
+
+  private markTyping(clientId: string): void {
+    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 });
+    }
+  }
+
+  private markStopped(clientId: string): void {
+    const existing = this.typers.get(clientId);
+    if (!existing) {
+      return;
+    }
+    clearTimeout(existing);
+    this.typers.delete(clientId);
+    this.emit({ type: 'stopped', clientId });
+  }
+
+  private emit(change: TypingEvent['change']): void {
+    const event: TypingEvent = { currentlyTyping: new Set(this.typers.keys()), change };
+    for (const listener of [...this.listeners]) {
+      listener(event);
+    }
+  }
+}

package/src/util.ts

@@ -0,0 +1,12 @@
+/** Small internal helpers shared across chat features. */
+
+/**
+ * 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.
+ */
+export function newMessageId(): string {
+  const random = Math.floor(Math.random() * 0x1_0000_0000).toString(16).padStart(8, '0');
+  return `${Date.now()}-${random}`;
+}