@foony/chat 0.0.1

package/LICENSE

@@ -0,0 +1,215 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one of
+          the following places: within a NOTICE text file distributed as
+          part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Foony Limited
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,67 @@
+# @foony/chat
+
+A chat API — rooms, messages (with edit/delete), typing indicators, room
+reactions, presence, occupancy, and history — built on top of
+[`@foony/realtime`](../realtime-js). It adds no new transport; it rides the
+existing realtime connection and maps each chat feature onto pub/sub event
+names on a per-room channel (`chat:<roomName>`).
+
+```ts
+import { Realtime } from '@foony/realtime';
+import { ChatClient } from '@foony/chat';
+
+const realtime = new Realtime({ authCallback });
+const chat = new ChatClient(realtime);
+
+const room = chat.rooms.get('general');
+await room.attach();
+
+room.messages.subscribe((event) => {
+  // event.type is 'created' | 'updated' | 'deleted'
+  console.log(event.message.text);
+});
+
+const message = await room.messages.send({ text: 'Hello!' });
+await room.messages.update(message.id, { text: 'Hello, world!' });
+await room.messages.delete(message.id);
+
+// Backfill recent history (materialized through the same reconciler).
+const page = await room.messages.history({ limit: 50 });
+
+// Presence, typing, reactions, occupancy
+await room.presence.enter({ name: 'Alice' });
+await room.typing.keystroke();
+await room.reactions.send({ name: '🎉' });
+room.occupancy.subscribe(({ connections, presenceMembers }) => {});
+```
+
+## Design notes
+
+- **Messages** are keyed by a stable, sender-assigned `id`, so `update(id, …)`
+  and `delete(id, …)` reference a message directly. Edits/deletes are published
+  as new frames and reconciled client-side by `id`; the same reconciler runs
+  over the live stream and over `history()`, so both converge on identical
+  state regardless of delivery order or duplicates.
+- **Typing** is ephemeral: a heartbeat is throttled to `heartbeatThrottleMs`
+  (default 10s, must be uniform across clients), and receivers auto-expire a
+  typer ~2s after the last heartbeat.
+- **Occupancy** is derived entirely from the presence set — `presenceMembers`
+  counts distinct client ids, `connections` counts distinct
+  (clientId, connectionId) pairs. It counts only members who entered presence.
+- **React** bindings are intentionally out of this core package and planned as
+  a separate `@foony/chat/react` subpath.
+
+## Examples
+
+Runnable browser + Node examples that exercise every feature live against the prod
+edge live in [`examples/`](./examples) (`npm run client` for the React playground,
+`npm run bot` for a Node participant). See [examples/README.md](./examples/README.md).
+
+## Scripts
+
+- `npm run build` — dual ESM (`lib/`) + CJS (`lib-cjs/`) build.
+- `npm test` — vitest unit tests.
+
+## License
+
+[Apache-2.0](./LICENSE) © Foony Limited

package/lib/chatClient.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 declare class ChatClient {
+    private readonly realtime;
+    /** Room registry and factory. */
+    readonly rooms: Rooms;
+    constructor(realtime: Realtime);
+    /** The underlying realtime connection (status, events). */
+    get connection(): 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;
+}
+//# sourceMappingURL=chatClient.d.ts.map

package/lib/chatClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatClient.d.ts","sourceRoot":"","sources":["../src/chatClient.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,+DAA+D;AAC/D,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAHrC,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;gBAEO,QAAQ,EAAE,QAAQ;IAI/C,2DAA2D;IAC3D,IAAI,UAAU,IAAI,UAAU,CAE3B;IAED;;;OAGG;IACH,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;CACF"}

package/lib/chatClient.js

@@ -0,0 +1,28 @@
+/**
+ * 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 { Rooms } from './rooms.js';
+/** Chat client built on top of a {@link Realtime} instance. */
+export class ChatClient {
+    realtime;
+    /** Room registry and factory. */
+    rooms;
+    constructor(realtime) {
+        this.realtime = realtime;
+        this.rooms = new Rooms(realtime, () => this.clientId);
+    }
+    /** The underlying realtime connection (status, events). */
+    get 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() {
+        return this.realtime.getClientId();
+    }
+}
+//# sourceMappingURL=chatClient.js.map

package/lib/chatClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatClient.js","sourceRoot":"","sources":["../src/chatClient.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,+DAA+D;AAC/D,MAAM,OAAO,UAAU;IAIQ;IAH7B,iCAAiC;IACxB,KAAK,CAAQ;IAEtB,YAA6B,QAAkB;QAAlB,aAAQ,GAAR,QAAQ,CAAU;QAC7C,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACxD,CAAC;IAED,2DAA2D;IAC3D,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;IAClC,CAAC;IAED;;;OAGG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;IACrC,CAAC;CACF"}

package/lib/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,KAAK,UAAU,EAAE,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EACV,OAAO,EACP,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,EACX,YAAY,EACZ,SAAS,IAAI,aAAa,EAC1B,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/lib/index.js

@@ -0,0 +1,18 @@
+/**
+ * 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 } from './room.js';
+export { Messages } from './messages.js';
+export { Presence } from './presence.js';
+export { Typing } from './typing.js';
+export { Reactions } from './reactions.js';
+export { Occupancy } from './occupancy.js';
+export { MessageReconciler } from './reconciler.js';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,IAAI,EAA+C,MAAM,WAAW,CAAC;AAC9E,OAAO,EAAE,QAAQ,EAAwB,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAyB,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,MAAM,EAAuB,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAyB,MAAM,gBAAgB,CAAC;AAClE,OAAO,EAAE,SAAS,EAA0B,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC"}

package/lib/messages.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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, UnsubscribeFn } from '@foony/realtime';
+import type { ChatMessageEvent, Message, MessagePage, SendMessageParams, UpdateMessageParams } from './types.js';
+/** Listener invoked for every materialized message change on the room. */
+export type MessageListener = (event: ChatMessageEvent) => void;
+/** The message feature of a {@link Room}. */
+export declare class Messages {
+    private readonly channel;
+    private readonly roomName;
+    private readonly getClientId;
+    private readonly reconciler;
+    private readonly listeners;
+    private channelUnsubscribe;
+    constructor(channel: Channel, roomName: string, getClientId: () => string | null);
+    /** Send a new message. Returns the message optimistically; its `id` is stable. */
+    send(params: SendMessageParams): Promise<Message>;
+    /** Edit a message by id. Replaces text/metadata/headers (omitted fields clear). */
+    update(id: string, params: UpdateMessageParams): Promise<void>;
+    /** Delete a message by id. */
+    delete(id: string): Promise<void>;
+    /**
+     * Subscribe to live message changes. The first subscriber attaches the
+     * underlying channel subscription; the last to unsubscribe removes it.
+     */
+    subscribe(listener: MessageListener): UnsubscribeFn;
+    /**
+     * 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.
+     */
+    history(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<MessagePage>;
+    /** Lazily attach the single channel subscription that feeds the reconciler. */
+    private ensureChannelSubscription;
+}
+//# sourceMappingURL=messages.d.ts.map

package/lib/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAgB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAG5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjH,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAUhE,6CAA6C;AAC7C,qBAAa,QAAQ;IAMjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAP9B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,kBAAkB,CAA8B;gBAGrC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,MAAM,GAAG,IAAI;IAKnD,kFAAkF;IAC5E,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IA0BvD,mFAAmF;IAC7E,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpE,8BAA8B;IACxB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAYnD;;;;OAIG;IACG,OAAO,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA0BjF,+EAA+E;IAC/E,OAAO,CAAC,yBAAyB;CAclC"}

package/lib/messages.js

@@ -0,0 +1,146 @@
+/**
+ * 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 { MESSAGE_EVENT, PAYLOAD_VERSION } from './protocol.js';
+import { MessageReconciler } from './reconciler.js';
+import { newMessageId } from './util.js';
+/**
+ * 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 {
+    channel;
+    roomName;
+    getClientId;
+    reconciler;
+    listeners = new Set();
+    channelUnsubscribe = null;
+    constructor(channel, roomName, getClientId) {
+        this.channel = channel;
+        this.roomName = roomName;
+        this.getClientId = getClientId;
+        this.reconciler = new MessageReconciler(roomName);
+    }
+    /** Send a new message. Returns the message optimistically; its `id` is stable. */
+    async send(params) {
+        const id = newMessageId();
+        const payload = {
+            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, params) {
+        const payload = {
+            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) {
+        const payload = { 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) {
+        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) {
+        const { messages: frames, more } = await this.channel.history({
+            ...(params?.limit === undefined ? {} : { limit: params.limit }),
+            ...(params?.cursor === undefined ? {} : { start: params.cursor }),
+        });
+        const touched = [];
+        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 !== undefined);
+        return {
+            messages,
+            hasMore: more,
+            ...(frames.length > 0 && frames[0] ? { nextCursor: frames[0].messageId } : {}),
+        };
+    }
+    /** Lazily attach the single channel subscription that feeds the reconciler. */
+    ensureChannelSubscription() {
+        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) {
+    const data = frame.data;
+    if (typeof data !== 'object' || data === null) {
+        return null;
+    }
+    const id = data['id'];
+    return typeof id === 'string' && id !== '' ? id : null;
+}
+//# sourceMappingURL=messages.js.map

package/lib/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAuB,MAAM,eAAe,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAKzC;;;;;GAKG;AACH,MAAM,cAAc,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjD,6CAA6C;AAC7C,MAAM,OAAO,QAAQ;IAMA;IACA;IACA;IAPF,UAAU,CAAoB;IAC9B,SAAS,GAAG,IAAI,GAAG,EAAmB,CAAC;IAChD,kBAAkB,GAAyB,IAAI,CAAC;IAExD,YACmB,OAAgB,EAChB,QAAgB,EAChB,WAAgC;QAFhC,YAAO,GAAP,OAAO,CAAS;QAChB,aAAQ,GAAR,QAAQ,CAAQ;QAChB,gBAAW,GAAX,WAAW,CAAqB;QAEjD,IAAI,CAAC,UAAU,GAAG,IAAI,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACpD,CAAC;IAED,kFAAkF;IAClF,KAAK,CAAC,IAAI,CAAC,MAAyB;QAClC,MAAM,EAAE,GAAG,YAAY,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAmB;YAC9B,CAAC,EAAE,eAAe;YAClB,MAAM,EAAE,QAAQ;YAChB,EAAE;YACF,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvE,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;SACrE,CAAC;QACF,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;QAC9E,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO;YACL,EAAE;YACF,QAAQ,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,EAAE;YAClC,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;YAC/B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,EAAE;YAC7B,SAAS,EAAE,GAAG;YACd,SAAS,EAAE,GAAG;YACd,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,KAAK;SACf,CAAC;IACJ,CAAC;IAED,mFAAmF;IACnF,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,MAA2B;QAClD,MAAM,OAAO,GAAmB;YAC9B,CAAC,EAAE,eAAe;YAClB,MAAM,EAAE,QAAQ;YAChB,EAAE;YACF,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;YACvE,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;SACrE,CAAC;QACF,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,8BAA8B;IAC9B,KAAK,CAAC,MAAM,CAAC,EAAU;QACrB,MAAM,OAAO,GAAmB,EAAE,CAAC,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;QAC7E,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,aAAa,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;IAChF,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,QAAyB;QACjC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAC7B,IAAI,CAAC,yBAAyB,EAAE,CAAC;QACjC,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAChC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBACzD,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBAC1B,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC;YACjC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,MAA4C;QACxD,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC;YAC5D,GAAG,CAAC,MAAM,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;YAC/D,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;SAClE,CAAC,CAAC;QACH,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBACjC,SAAS;YACX,CAAC;YACD,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC7B,MAAM,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;YAC9B,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;gBACzC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACnB,CAAC;QACH,CAAC;QACD,MAAM,QAAQ,GAAG,OAAO;aACrB,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;aACpC,MAAM,CAAC,CAAC,OAAO,EAAsB,EAAE,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC;QAClE,OAAO;YACL,QAAQ;YACR,OAAO,EAAE,IAAI;YACb,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC/E,CAAC;IACJ,CAAC;IAED,+EAA+E;IACvE,yBAAyB;QAC/B,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QACD,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE;YACxE,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC3C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,OAAO;YACT,CAAC;YACD,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;gBAC3C,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,oFAAoF;AACpF,SAAS,WAAW,CAAC,KAAmB;IACtC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACxB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,EAAE,GAAI,IAAgC,CAAC,IAAI,CAAC,CAAC;IACnD,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC"}

package/lib/occupancy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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;
+/** The occupancy feature of a {@link Room}. */
+export declare class Occupancy {
+    private readonly presence;
+    private readonly listeners;
+    private readonly debounceMs;
+    private debounceTimer;
+    private lastEmitted;
+    private membersChangedUnsubscribe;
+    constructor(presence: Presence, debounceMs?: number);
+    /** Current occupancy snapshot, computed from the local presence member set. */
+    get(): OccupancyData;
+    /** Subscribe to occupancy changes (debounced, deduplicated). */
+    subscribe(listener: OccupancyListener): UnsubscribeFn;
+    private scheduleEmit;
+}
+//# sourceMappingURL=occupancy.d.ts.map

package/lib/occupancy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"occupancy.d.ts","sourceRoot":"","sources":["../src/occupancy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D,qDAAqD;AACrD,MAAM,MAAM,iBAAiB,GAAG,CAAC,SAAS,EAAE,aAAa,KAAK,IAAI,CAAC;AAKnE,+CAA+C;AAC/C,qBAAa,SAAS;IAQlB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAP3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,yBAAyB,CAA8B;gBAG5C,QAAQ,EAAE,QAAQ,EACnC,UAAU,CAAC,EAAE,MAAM;IAKrB,+EAA+E;IAC/E,GAAG,IAAI,aAAa;IAMpB,gEAAgE;IAChE,SAAS,CAAC,QAAQ,EAAE,iBAAiB,GAAG,aAAa;IAkBrD,OAAO,CAAC,YAAY;CAgBrB"}