@axonkit/client-sdk-js 0.1.1 → 0.2.1

package/README.md

@@ -1,10 +1,18 @@
-# @axonkit/client-sdk-js
-
-AxonKit JavaScript/TypeScript Client SDK for real-time communication, built on top of [mediasoup-client](https://github.com/versatica/mediasoup-client).
-
-> **License**: This SDK is proprietary software licensed exclusively for use
-> with the AxonKit Service. See [LICENSE](./LICENSE) for the full terms.
-> For commercial inquiries, contact <jiyeyuran@gmail.com>.
+<p align="center">
+  <img src="assets/banner.svg" alt="AxonKit" width="480">
+</p>
+
+<p align="center">
+  <strong>AxonKit JavaScript/TypeScript client SDK</strong> for real-time communication,<br/>
+  built on <a href="https://github.com/versatica/mediasoup-client">mediasoup-client</a> with a
+  <a href="https://livekit.io">LiveKit</a>-compatible API surface.
+</p>
+
+<p align="center">
+  <a href="https://github.com/axonkit/client-sdk-js/actions/workflows/publish.yml"><img alt="CI" src="https://github.com/axonkit/client-sdk-js/actions/workflows/publish.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/@axonkit/client-sdk-js"><img alt="npm version" src="https://img.shields.io/npm/v/@axonkit/client-sdk-js"></a>
+  <a href="https://www.npmjs.com/package/@axonkit/client-sdk-js"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@axonkit/client-sdk-js"></a>
+</p>
 
 ## Installation
 
@@ -15,94 +23,105 @@ pnpm add @axonkit/client-sdk-js
 ## Quick Start
 
 ```typescript
-import { Room, RoomState, setLogLevel, LogLevel } from '@axonkit/client-sdk-js';
+import {
+  Room,
+  RoomEvent,
+  ConnectionState,
+  setLogLevel,
+  LogLevel,
+} from '@axonkit/client-sdk-js';
 
 setLogLevel(LogLevel.INFO);
 
 const room = new Room({
-  autoSubscribe: true,
-  dynacast: true,
-  adaptiveStream: true,
+  dynacast: true,        // pause simulcast layers with no subscribers
+  adaptiveStream: true,  // adapt subscription quality to element size/visibility
 });
 
-// Connect
+// Subscribe to events before connecting
+room
+  .on(RoomEvent.ParticipantConnected, (participant) => {
+    console.log(`${participant.identity} joined`);
+  })
+  .on(RoomEvent.ParticipantDisconnected, (participant) => {
+    console.log(`${participant.identity} left`);
+  })
+  .on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
+    const element = track.attach();
+    if (track.kind === 'video') {
+      document.getElementById('remote-videos')?.appendChild(element);
+    } else {
+      element.play();
+    }
+  });
+
+// Connect (token is optional when the server allows anonymous joins —
+// pass roomName in RoomOptions instead)
 await room.connect('https://your-server.com', 'your-jwt-token');
 
 // Publish camera and microphone
 await room.localParticipant.setCameraEnabled(true);
 await room.localParticipant.setMicrophoneEnabled(true);
 
-// Listen for remote tracks
-room.on('trackSubscribed', (track, publication, participant) => {
-  if (track.kind === 'video') {
-    const element = track.attach();
-    document.getElementById('remote-videos')?.appendChild(element);
-  } else {
-    const element = track.attach();
-    element.play();
-  }
-});
-
-// Listen for participants
-room.on('participantJoined', (participant) => {
-  console.log(`${participant.identity} joined`);
-});
-
-room.on('participantLeft', (participant) => {
-  console.log(`${participant.identity} left`);
-});
-
-// Disconnect
+// Later
 await room.disconnect();
 ```
 
 ## Features
 
-- **WebRTC Transport** — Powered by mediasoup-client for reliable media transport
-- **DataChannel RPC** — Axon Protocol for signaling over DataChannel (after initial HTTP join)
-- **Auto Subscribe** — Automatically subscribe to new tracks
-- **Dynacast** — Dynamic simulcast layer control based on subscriber needs
-- **Adaptive Stream** — Visibility and size-based subscription management
-- **Reconnection** — Automatic reconnect with exponential backoff and state sync
-- **Heartbeat** — Ping/pong keep-alive with RTT measurement
+- **LiveKit-compatible API** — familiar `Room` / `Participant` / `Track` model, events, and options
+- **mediasoup-client transport** — WebRTC media over mediasoup send/receive transports
+- **DataChannel RPC** — Axon Protocol for signaling over DataChannel after the initial HTTP join
+- **Auto Subscribe** — server-side subscription management with no media loss
+- **Simulcast / SVC** — simulcast layers, scalability modes, backup codec policies
+- **Dynacast** — dynamically pause video encodings with no subscribers
+- **Adaptive Stream** — visibility and size-based subscription management
+- **Reconnection** — automatic reconnect with pluggable reconnect policy and state sync
+- **Data streams & RPC** — sendText/streamText/sendFile/streamBytes and typed RPC between participants
+- **Groups** — breakout-room style participant grouping with pin/move
+- **Room shared state** — server-backed key/value state with offline catch-up
 
 ## API Reference
 
 ### Room
 
-| Method                | Description                                |
-| --------------------- | ------------------------------------------ |
-| `connect(url, token)` | Connect to a room                          |
-| `disconnect()`        | Disconnect from the room                   |
-| `startAudio()`        | Start audio playback (for autoplay policy) |
+| Method | Description |
+| --- | --- |
+| `connect(url, token?, options?)` | Connect to a room (token optional for anonymous servers) |
+| `disconnect(stopTracks?)` | Disconnect and optionally stop local tracks |
+| `switchActiveDevice(kind, deviceId)` | Switch camera / microphone / output device |
+| `startAudio()` | Resume audio playback (autoplay policy) |
 
 ### LocalParticipant
 
-| Method                           | Description                 |
-| -------------------------------- | --------------------------- |
-| `setCameraEnabled(enabled)`      | Toggle camera               |
-| `setMicrophoneEnabled(enabled)`  | Toggle microphone           |
-| `setScreenShareEnabled(enabled)` | Toggle screen share         |
-| `publishTrack(track, options?)`  | Publish a local track       |
-| `unpublishTrack(track)`          | Unpublish a track           |
-| `publishData(data, options?)`    | Send data via DataChannel   |
-| `updateMetadata(metadata)`       | Update participant metadata |
-| `updateName(name)`               | Update participant name     |
+| Method | Description |
+| --- | --- |
+| `setCameraEnabled(enabled)` | Toggle camera |
+| `setMicrophoneEnabled(enabled)` | Toggle microphone |
+| `setScreenShareEnabled(enabled)` | Toggle screen share |
+| `publishTrack(track, options?)` | Publish a local track |
+| `unpublishTrack(track, stopOnUnpublish?)` | Unpublish a track |
+| `publishData(data, options?)` | Send data via DataChannel |
+| `setMetadata(metadata)` | Update participant metadata |
+| `setName(name)` | Update participant display name |
 
 ### Events
 
+Subscribe with the `RoomEvent` enum (values are camelCase, matching LiveKit):
+
 ```typescript
-room.on('connected', () => {});
-room.on('disconnected', (reason) => {});
-room.on('reconnecting', () => {});
-room.on('reconnected', () => {});
-room.on('participantJoined', (participant) => {});
-room.on('participantLeft', (participant) => {});
-room.on('trackSubscribed', (track, publication, participant) => {});
-room.on('trackUnsubscribed', (track, publication, participant) => {});
-room.on('activeSpeakersChanged', (speakers) => {});
+room.on(RoomEvent.Connected, () => {});
+room.on(RoomEvent.Disconnected, (reason) => {});
+room.on(RoomEvent.Reconnecting, () => {});
+room.on(RoomEvent.ParticipantConnected, (participant) => {});
+room.on(RoomEvent.ParticipantDisconnected, (participant, reason) => {});
+room.on(RoomEvent.TrackSubscribed, (track, publication, participant) => {});
+room.on(RoomEvent.TrackUnsubscribed, (track, publication, participant) => {});
+room.on(RoomEvent.ActiveSpeakersChanged, (speakers) => {});
 ```
 
+Full API documentation is generated with TypeDoc: `pnpm run docs`.
+
 ## Building
 
 ```bash
@@ -118,8 +137,10 @@ Outputs:
 
 ## Demo
 
-Open `examples/demo/index.html` in a browser after building. Requires a running AxonKit server.
+Open `examples/demo/index.html` in a browser after building. Requires a running [AxonKit server](https://github.com/axonkit/axonkit).
 
 ## License
 
-MIT
+This SDK is proprietary software licensed exclusively for use with the AxonKit
+Service. See [LICENSE](./LICENSE) for the full terms. For commercial inquiries,
+contact <jiyeyuran@gmail.com>.

package/dist/Room.d.ts

@@ -4,7 +4,7 @@ import { RemoteParticipant } from './participant/RemoteParticipant';
 import { Participant } from './participant/Participant';
 import { LocalTrackPublication } from './participant/LocalTrackPublication';
 import type { RemoteTrackPublication } from './participant/RemoteTrackPublication';
-import { RoomState, DisconnectReason, StreamState, type RoomInfo, type ServerInfo, type GroupInfo, ConnectionQuality } from './protocol/types';
+import { ConnectionState, DisconnectReason, StreamState, type ServerInfo, type GroupInfo, ConnectionQuality } from './protocol/types';
 import type { RoomOptions, RoomConnectOptions } from './room/options';
 import { Track } from './track/Track';
 import { RoomEvent } from './events';
@@ -14,12 +14,12 @@ export type RoomEvents = {
     [RoomEvent.Disconnected]: (reason?: DisconnectReason) => void;
     [RoomEvent.Reconnecting]: () => void;
     [RoomEvent.Reconnected]: () => void;
-    [RoomEvent.ConnectionStateChanged]: (state: RoomState) => void;
+    [RoomEvent.ConnectionStateChanged]: (state: ConnectionState) => void;
     [RoomEvent.SignalReconnecting]: () => void;
     [RoomEvent.MediaDevicesChanged]: () => void;
     [RoomEvent.MediaDevicesError]: (error: Error) => void;
-    [RoomEvent.ParticipantJoined]: (participant: RemoteParticipant) => void;
-    [RoomEvent.ParticipantLeft]: (participant: RemoteParticipant, reason?: string) => void;
+    [RoomEvent.ParticipantConnected]: (participant: RemoteParticipant) => void;
+    [RoomEvent.ParticipantDisconnected]: (participant: RemoteParticipant, reason?: DisconnectReason) => void;
     [RoomEvent.ParticipantUpdated]: (participant: RemoteParticipant) => void;
     [RoomEvent.ParticipantMetadataChanged]: (prevMetadata: string | undefined, participant: Participant) => void;
     [RoomEvent.ParticipantNameChanged]: (name: string, participant: Participant) => void;
@@ -35,11 +35,15 @@ export type RoomEvents = {
     [RoomEvent.LocalTrackUnpublished]: (publication: LocalTrackPublication, participant: LocalParticipant) => void;
     [RoomEvent.LocalAudioSilenceDetected]: () => void;
     [RoomEvent.ActiveSpeakersChanged]: (speakers: Participant[]) => void;
-    [RoomEvent.RoomUpdated]: (room: RoomInfo) => void;
-    [RoomEvent.DataReceived]: (data: ArrayBuffer, participant?: RemoteParticipant) => void;
+    [RoomEvent.RoomMetadataChanged]: (metadata: string | undefined) => void;
+    [RoomEvent.DataReceived]: (payload: Uint8Array, participant?: RemoteParticipant) => void;
     [RoomEvent.ConnectionQualityChanged]: (quality: ConnectionQuality, participant: Participant) => void;
     [RoomEvent.AudioPlaybackStatusChanged]: (canPlayback: boolean) => void;
     [RoomEvent.VideoPlaybackStatusChanged]: (canPlayback: boolean) => void;
+    [RoomEvent.SignalConnected]: () => void;
+    [RoomEvent.ActiveDeviceChanged]: (kind: MediaDeviceKind, deviceId: string) => void;
+    [RoomEvent.RecordingStatusChanged]: (recording: boolean) => void;
+    [RoomEvent.ParticipantPermissionsChanged]: (prevPermissions: import('./protocol/types').ParticipantPermission | undefined, participant: Participant) => void;
     [RoomEvent.ChatMessage]: (message: Message, participant?: Participant) => void;
     [RoomEvent.MessageDeleted]: (ids: string[], type?: string) => void;
     [RoomEvent.StateUpdated]: (key: string, value: string, participantSid?: string, participantIdentity?: string) => void;
@@ -88,7 +92,7 @@ export declare class Room extends TypedEmitter<RoomEvents> {
     private _lastMessageTimestamp;
     private _connectOptions;
     constructor(options?: RoomOptions);
-    get state(): RoomState;
+    get state(): ConnectionState;
     get name(): string;
     get sid(): string;
     get serverInfo(): ServerInfo | undefined;