@talkjs/core/README.md

Lets you connect to your TalkJS chat as a user and read, subscribe to, and update your chat data.

# TalkJS Core

The `@talkjs/core` package lets you connect to your [TalkJS](https://talkjs.com) chat as a user and read, subscribe to, and update your chat data.

[See our docs](https://talkjs.com/docs/Reference/JavaScript_Data_API/) for more information.

## Prerequisites

To use this package, you will need a [TalkJS account](https://talkjs.com/dashboard/login). TalkJS provides a ready-to-use chat client for your application. Your account gives you access to TalkJS's free development environment.

## Example

This example demonstrates how to create a TalkJS session and then create two users and conversation between them.

Install the `@talkjs/core` package:

```sh
npm install @talkjs/core
# or
yarn add @talkjs/core
```

Import it into the component where you want to use it:

```js
import { getTalkSession } from "@talkjs/core";
```

Then add the following code to create the session, users and conversation:

```js
// Replace with your own app ID
const appId = "<APP_ID>";
const userId = "alice";

const session = getTalkSession({ appId, userId });
session.currentUser.createIfNotExists({ name: "Alice" });

const conversation = session.conversation("my_conversation");
conversation.createIfNotExists();

conversation.subscribeMessages((messages) => {
  console.log(messages);
});
```

For example, if you are using React, add this code inside a `useEffect` hook.

## Node.js compatibility

This package is primarily intended to be used in the browser because it only connects as a single user. However, it also works in Node.js.

The `@talkjs/core` package uses `WebSocket`s to create a connection to the TalkJS servers. If you use `@talkjs/core` in the browser or in Node.js version 22, it will use the built-in `WebSocket` implementation automatically. Node.js version 21 will also use the built-in implementation if the `--experimental-websocket` flag is enabled.

If you are using an older version of Node.js without built-in support for `WebSocket`s, you will need to add support with a library. We recommend installing the [ws](https://www.npmjs.com/package/ws) package. Then tell `@talkjs/core` to use `WebSocket` from the library:

```js
import { getTalkSession, registerPolyfills } from "@talkjs/core";
import { WebSocket } from "ws";

registerPolyfills({ WebSocket: WebSocket });

const session = getTalkSession(...);
```

## Support

If you encounter any problems with `@talkjs/core`, please open a [chat with support](https://talkjs.com/?chat). TalkJS support is staffed by engineers.

## Changelog

### 1.3.0

- Added `TalkSession.subscribeConversations` which returns a windowed subscription to your most recently active conversations.
  - Added `ConversationListSubscription`

### 1.2.0

- Added `ConversationRef.subscribeParticipants` which returns a windowed subscription to the participants in the conversation.
  - Added `ParticipantSubscription` and `ParticipantActiveState`.
- Improved startup time by sending queued requests faster when you first open the connection.

### 1.1.1

- Added `ConversationSnapshot.everyoneReadUntil` which is the minimum of all the participants' `readUntil` values.

### 1.1.0

- Added `ConversationRef.subscribeTyping` which lets you subscribe to typing indicators in a conversation.
  - Added `TypingSubscription`, `TypingSnapshot`, `ManyTypingSnapshot`, `FewTypingSnapshot`

### 1.0.1

- Fixed a bug with `ConversationRef.subscribe` where it would emit the same snapshot multiple times in a row, when old messages were edited or deleted.
- Exported types for `GenericFileMetadata`, `AudioFileMetadata`, `ImageFileMetadata`, `VideoFileMetadata`, and `VoiceRecordingFileMetadata`

### 1.0.0

- Initial Release