call-engine-wx 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# call-engine-wx
+
+Pure-JS `TUICallEngine` for WeChat Mini Program. **No WASM.**
+
+API shape mirrors [`@trtc/call-engine-lite-wx`](../TUICallEngine-wx) so
+that `TUICallKit` and existing business code can switch over without
+changing event names or method signatures.
+
+## Why?
+
+The legacy SDK ships a C++ core compiled to WASM plus a JS glue layer.
+That works, but it adds ~hundreds of KB to the WeChat MP package and
+requires a WASM-capable runtime. For the subset of API actually used in
+production we can implement the call state machine directly in JS on
+top of `@tencentcloud/lite-chat` and `@tencentcloud/trtc-cloud-wx`,
+shaving most of the bundle weight.
+
+`call-engine-wx` is the JS-only reimplementation. This cut implements
+**login / logout / `calls`** plus the event plumbing. The remaining
+call-signalling APIs (`call` / `accept` / `reject` / `hangup` / ...)
+will land in follow-up increments on top of the same lite-chat session.
+
+> **Note on transport.** `calls` does NOT use lite-chat's
+> `createInvitation` / `onNewInvitationReceived` business APIs. It
+> talks directly to the v3 backend service `call_engine_srv` via
+> `chat.callExperimentalAPI('sendCallEngineSSOPacket', ...)` —
+> the same mechanism used by the sibling pure-JS package
+> `call-engine-wx`. The wire protocol is byte-identical to the C++
+> reference at `tuikit_engine/src/pipeline/call/module/v3_call/`.
+
+## Install
+
+```bash
+pnpm add call-engine-wx @tencentcloud/lite-chat
+# only if you'll call getTRTCCloudInstance() / video features
+pnpm add @tencentcloud/trtc-cloud-wx
+```
+
+`@tencentcloud/trtc-cloud-wx` is declared as an **optional**
+peer-dependency. If your use case is "just login / receive offline
+invites", you do not need to install it.
+
+## Quickstart
+
+```js
+import TUICallEngine, { TUICallEvent } from 'call-engine-wx';
+
+TUICallEngine.once('ready', async () => {
+  const engine = TUICallEngine.createInstance({ SDKAppID });
+
+  engine.on(TUICallEvent.SDK_READY, () => {
+    console.log('SDK ready');
+  });
+  engine.on(TUICallEvent.KICKED_OUT, () => { /* ... */ });
+  engine.on(TUICallEvent.onUserSigExpired, () => { /* refresh userSig */ });
+
+  await engine.login({ userID, userSig });
+});
+```
+
+### With an existing lite-chat instance
+
+```js
+import TencentCloudChat from '@tencentcloud/lite-chat';
+import TUICallEngine from 'call-engine-wx';
+
+const tim = TencentCloudChat.create({ SDKAppID });
+const engine = TUICallEngine.createInstance({ SDKAppID, tim });
+await engine.login({ userID, userSig });
+```
+
+## API (already implemented)
+
+| Method | Notes |
+| --- | --- |
+| `TUICallEngine.createInstance(options)` | Singleton create / reuse. |
+| `TUICallEngine.once('ready', fn)` | Fires on next microtask (no WASM to wait for). |
+| `engine.login({ userID, userSig })` | Calls `tim.login`, emits `SDK_READY`. |
+| `engine.logout()` | Calls `tim.logout`. |
+| `engine.destroyInstance()` | Logout + unbind + drop singleton. |
+| `engine.on / off / once` | Local event bus. |
+| `engine.getTim()` | Underlying lite-chat instance. |
+| `engine.getTRTCCloudInstance()` | Lazy `TRTCCloud.createInstance()`. |
+| `engine.setLogLevel(level)` | Forwarded to lite-chat. |
+| `engine.calls(params)` | Multi-party call. Enters the TRTC room and sends `call_engine_srv.start_call`. See below. |
+
+### `engine.calls(params)`
+
+```js
+const { inviteId, roomId, callResultList } = await engine.calls({
+  inviteeList: ['userA', 'userB'],
+  mediaType: CallMediaType.VIDEO,    // or CallMediaType.AUDIO
+  groupID: 'optional-group-id',
+  // roomID: 12345678,               // optional, auto-generated if absent
+  timeout: 30,                       // seconds
+  userData: 'free-form string',
+  // offlinePushInfo: { ... }        // optional, see ICallsParams type
+});
+```
+
+The return shape:
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `inviteId` | `string` | Server-issued call_id; needed for cancel / accept / hangup. |
+| `roomId` | `{ intRoomId, strRoomId }` | The TRTC room actually joined. |
+| `callResultList` | `Array` | Per-callee outcome (`SUCCESS` / `INVITED` / `LINE_BUSY`). |
+
+Side effects emitted on the engine event bus:
+
+- `onUserJoin(userId)` for each invitee with `INVITED` (1)
+- `onUserInviting(userId)` for each invitee with `SUCCESS` (0)
+- `onUserLineBusy(userId)` for each invitee with `LINE_BUSY` (2)
+- `onCallNotConnected({ callInfo, userId, reason: LINE_BUSY })` if every
+  invitee returned busy. The TRTC room is left automatically in that case.
+
+If `start_call` fails (transport error or backend rejection), the engine
+leaves the TRTC room and rejects the promise with `{ code, message }`.
+
+## API (not yet implemented)
+
+`call` / `accept` / `reject` / `hangup` / `inviteUser` /
+`switchCallMediaType` / `openCamera` / `closeCamera` / `openMicrophone` /
+`closeMicrophone` / `startRemoteView` / `stopRemoteView` / ...
+
+These will be added on top of the same lite-chat session, using the
+backend `call_engine_srv` SSO protocol — no WASM involved.