npm package: @patra-cid/wasm-client-sdk
Description: open im sdk for web
Author: tedy
Latest version: 3.8.23

# @inter-digital/wasm-client-sdk

JavaScript/TypeScript Client SDK for OpenIM (forked & maintained by Inter Digital) 👨‍💻💬

Use this SDK to add instant messaging capabilities to your application. By connecting to a self-hosted [OpenIM](https://www.openim.online/) server, you can quickly integrate instant messaging capabilities into your app with just a few lines of code.

The underlying SDK core is implemented in [OpenIM SDK Core](https://github.com/openimsdk/openim-sdk-core). Using the [WebAssembly](https://webassembly.org/) support provided by Go language, it can be compiled into wasm for web integration. The web interacts with the [OpenIM SDK Core](https://github.com/openimsdk/openim-sdk-core) through JSON, and the SDK exposes a re-encapsulated API for easy usage. In terms of data storage, JavaScript handles the logic of the SQL layer by virtualizing SQLite and storing it in IndexedDB using [sql.js](https://sql.js.org/).

## Documentation 📚

Visit [https://docs.openim.io/](https://docs.openim.io/) for detailed documentation and guides.

For the SDK reference, see [https://docs.openim.io/sdks/quickstart/browser](https://docs.openim.io/sdks/quickstart/browser).

## Installation 💻

### Adding Dependencies

```shell
npm install @inter-digital/wasm-client-sdk --save
```

Or install a specific version:

```shell
npm install @inter-digital/wasm-client-sdk@3.8.4-patch.25 --save
```

### Obtaining Required Static Resources for WASM

Follow these steps to obtain the static resources required for WebAssembly (WASM):

1. Locate the `@inter-digital/wasm-client-sdk` subdirectory in the `node_modules` directory of your project. Copy all the files in the `assets` folder to your project's public resource directory.

   The files to be copied are:

   - `openIM.wasm`
   - `sql-wasm.wasm`
   - `wasm_exec.js`

2. After copying the files, import the `wasm_exec.js` file in your `index.html` file using a `<script>` tag.

### Possible Issues ❗

> If you are using webpack4, you may follow this issue [How to import @openim/wasm-client-sdk in webpack4.x](https://github.com/openimsdk/open-im-sdk-web-wasm/issues/73).

## Usage 🚀

The following examples demonstrate how to use the SDK. TypeScript is used, providing complete type hints.

### Importing the SDK

```typescript
import { getSDK } from '@inter-digital/wasm-client-sdk';

const OpenIM = getSDK();
```

### Logging In and Listening for Connection Status

> Note: You need to [deploy](https://github.com/openimsdk/open-im-server#rocket-quick-start) OpenIM Server first, the default port of OpenIM Server is 10001, 10002.

```typescript
import { CbEvents } from '@inter-digital/wasm-client-sdk';
import type { WSEvent } from '@inter-digital/wasm-client-sdk/lib/types/entity';

OpenIM.on(CbEvents.OnConnecting, handleConnecting);
OpenIM.on(CbEvents.OnConnectFailed, handleConnectFailed);
OpenIM.on(CbEvents.OnConnectSuccess, handleConnectSuccess);

OpenIM.login({
  userID: 'IM user ID',
  token: 'IM user token',
  platformID: 5,
  apiAddr: 'http://your-server-ip:10002',
  wsAddr: 'ws://your-server-ip:10001',
});

function handleConnecting() {
  // Connecting...
}

function handleConnectFailed({ errCode, errMsg }: WSEvent) {
  // Connection failed ❌
  console.log(errCode, errMsg);
}

function handleConnectSuccess() {
  // Connection successful ✅
}
```

To log into the IM server, you need to create an account and obtain a user ID and token. Refer to the [access token documentation](https://docs.openim.io/restapi/userManagement/userRegister) for details.

### Receiving and Sending Messages 💬

OpenIM makes it easy to send and receive messages. By default, there is no restriction on having a friend relationship to send messages (although you can configure other policies on the server). If you know the user ID of the recipient, you can conveniently send a message to them.

```typescript
import { CbEvents } from '@inter-digital/wasm-client-sdk';
import type {
  WSEvent,
  MessageItem,
} from '@inter-digital/wasm-client-sdk/lib/types/entity';

// Listen for new messages 📩
OpenIM.on(CbEvents.OnRecvNewMessages, handleNewMessages);

const message = (await OpenIM.createTextMessage('hello openim')).data;

OpenIM.sendMessage({
  recvID: 'recipient user ID',
  groupID: '',
  message,
})
  .then(() => {
    // Message sent successfully ✉️
  })
  .catch(err => {
    // Failed to send message ❌
    console.log(err);
  });

function handleNewMessages({ data }: WSEvent<MessageItem[]>) {
  // New message list 📨
  console.log(data);
}
```

## Development & Publishing 🛠️

This project includes a `Makefile` to streamline building and publishing.

### Prerequisites

- Node.js >= 12.0
- npm with access to the `@inter-digital` organization
- An authenticator app for OTP (if 2FA is enabled on npm)

### Available Make Commands

| Command              | Description                                              |
| -------------------- | -------------------------------------------------------- |
| `make help`          | Show all available targets with descriptions             |
| `make install`       | Install dependencies                                     |
| `make build`         | Build the package                                        |
| `make clean`         | Remove build artifacts (`lib/`)                          |
| `make version`       | Show current package name and version                    |
| `make bump-patch`    | Bump the patch number (e.g. `patch.25` → `patch.26`)    |
| `make dry-run`       | Build and perform a publish dry run (no actual publish)  |
| `make publish`       | Build and publish to npm with `patch` tag                |
| `make publish-latest`| Build and publish to npm with `latest` tag               |
| `make tag-latest`    | Update the `latest` dist-tag to the current version      |
| `make release`       | Full flow — bump version, build, and publish             |
| `make login`         | Login to npm                                             |
| `make whoami`        | Check current npm user                                   |

### Quick Start: Publishing a New Version

1. **First-time setup** — login to npm:

   ```shell
   make login
   ```

2. **Full release** — bump version, build, and publish in one command:

   ```shell
   make release
   ```

   This will:
   - Bump the patch number (e.g. `3.8.4-patch.25` → `3.8.4-patch.26`)
   - Build the project
   - Prompt for your OTP and publish to npm

3. **Promote to latest** (optional) — if you want the new version to be the default when users run `npm install`:

   ```shell
   make tag-latest
   ```

### Step-by-Step Publishing

If you prefer more control, run each step individually:

```shell
# 1. Bump the version
make bump-patch

# 2. Build the project
make build

# 3. Preview what will be published
make dry-run

# 4. Publish to npm
make publish
```

### npm Tags

- **`patch`** — Used by default when publishing prerelease versions (e.g. `3.8.4-patch.25`). Users install with `npm install @inter-digital/wasm-client-sdk@patch`.
- **`latest`** — The default tag shown on the npm website. Users get this version when running `npm install @inter-digital/wasm-client-sdk` without specifying a version.

Use `make publish-latest` or `make tag-latest` to update the `latest` tag.

### CI/CD: Publishing to GitHub Packages

This project includes a GitHub Actions workflow that **builds and publishes** to GitHub Packages whenever a version tag (`v*`) is pushed.

> **Note:** The CI publishes to **GitHub Packages** (`@1nterdigital/wasm-client-sdk`). For publishing to **npm** (`@inter-digital/wasm-client-sdk`), use the Makefile commands described above.

#### How It Works

1. You make changes, push commits as many times as you want — **nothing happens**
2. When you're ready to release, you bump the version, commit, tag, and push the tag
3. The CI workflow triggers and automatically:
   - Installs dependencies and builds the project
   - Publishes the version to GitHub Packages
4. A summary with the published version and install command is shown in the GitHub Actions run

#### Setup

No additional secrets are needed — the workflow uses the built-in `GITHUB_TOKEN` which is automatically provided by GitHub Actions.

#### Usage

```shell
# 1. Make your changes

# 2. Bump version in package.json
make bump-patch

# 3. Build (optional, to verify locally)
make build

# 4. Commit and tag
git add .
git commit -m "v3.8.4-patch.26"
git tag v3.8.4-patch.26

# 5. Push commits and tag
git push && git push --tags
```

Only the tag push (`v*`) triggers the CI. Regular commits and branch pushes do **not** trigger a build.

#### Installing from GitHub Packages (for consumers)

To install the package from GitHub Packages in your other projects, you need to configure your `.npmrc`:

1. Create a `.npmrc` file in your project root:

   ```
   @1nterdigital:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
   ```

2. Set the `GITHUB_TOKEN` environment variable with a [Personal Access Token](https://github.com/settings/tokens) that has `read:packages` permission. Or replace `${GITHUB_TOKEN}` with your token directly (not recommended for shared repos).

3. Install the package:

   ```shell
   npm install @1nterdigital/wasm-client-sdk
   ```

#### Workflow File

The workflow configuration is located at `.github/workflows/publish-inter.yml`.

## Examples 🌟

You can find a demo web app that uses the SDK in the [openim-pc-web-demo](https://github.com/openimsdk/open-im-pc-web-demo) repository.

## Browser Support 🌐

| Browser             | Desktop OS            | Mobile OS |
| ------------------- | --------------------- | --------- |
| Chrome (61+)        | Windows, macOS, Linux | Android   |
| Firefox (58+)       | Windows, macOS, Linux | Android   |
| Safari (15+)        | macOS                 | iOS       |
| Edge (Chromium 16+) | Windows, macOS        |           |

## License :page_facing_up:

This software is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.