@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 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. Using the WebAssembly support provided by Go language, it can be compiled into wasm for web integration. The web interacts with the 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.

Documentation 📚

Visit https://docs.openim.io/ for detailed documentation and guides.

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

Installation 💻

Adding Dependencies

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

Or install a specific version:

npm install @inter-digital/[email protected] --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.

Usage 🚀

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

Importing the SDK

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

const OpenIM = getSDK();

Logging In and Listening for Connection Status

Note: You need to deploy OpenIM Server first, the default port of OpenIM Server is 10001, 10002.

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 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.

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:

   make login

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

   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:

   make tag-latest

Step-by-Step Publishing

If you prefer more control, run each step individually:

# 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

# 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 that has read:packages permission. Or replace ${GITHUB_TOKEN} with your token directly (not recommended for shared repos).

3. Install the package:

   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 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 file for details.