@axonkit/client-sdk-js 0.1.0

package/LICENSE

@@ -0,0 +1,85 @@
+AxonKit Client SDK License Agreement
+
+Copyright (c) 2026 axonkit. All rights reserved.
+
+1. Definitions
+   1.1 "SDK" means this software package and all source code, compiled
+       artifacts, type declarations, documentation, and related files
+       distributed under this Agreement.
+   1.2 "Service" means the AxonKit hosted services, APIs, and backend
+       systems operated by axonkit.
+   1.3 "You" (or "Licensee") means the individual or legal entity
+       exercising rights under this Agreement.
+
+2. License Grant
+   Subject to Your compliance with this Agreement, axonkit grants You a
+   limited, worldwide, non-exclusive, non-transferable, non-sublicensable,
+   revocable license to:
+     (a) install and use the SDK in source or compiled form solely for
+         the purpose of developing, testing, and operating applications
+         that connect to and interact with the Service; and
+     (b) redistribute the SDK as an integrated, non-separable component
+         of Your applications that use the Service, provided that the SDK
+         is not made available as a standalone product.
+
+3. Restrictions
+   You shall not, and shall not permit any third party to:
+     (a) use the SDK to connect to, interoperate with, or build any
+         service other than the Service;
+     (b) reverse engineer, decompile, disassemble, or otherwise attempt
+         to derive the source code of the SDK, except to the extent such
+         restriction is prohibited by applicable law;
+     (c) modify, translate, or create derivative works of the SDK for
+         the purpose of distributing them as a standalone library or to
+         third parties not using the Service;
+     (d) remove, alter, or obscure any copyright, trademark, or other
+         proprietary notices contained in the SDK;
+     (e) use the SDK to build, train, or develop a competing product or
+         service that is substantially similar to the Service; or
+     (f) sublicense, sell, rent, lease, lend, or otherwise transfer the
+         SDK to any third party except as expressly permitted in
+         Section 2(b).
+
+4. Ownership
+   The SDK is licensed, not sold. axonkit and its licensors retain all
+   right, title, and interest in and to the SDK, including all
+   intellectual property rights. No rights are granted to You other
+   than those expressly set forth in this Agreement.
+
+5. Third-Party Components
+   The SDK may include or depend on third-party open source software,
+   each of which is subject to its own license terms. Such third-party
+   licenses are not affected by this Agreement.
+
+6. Termination
+   This Agreement is effective until terminated. axonkit may terminate
+   this Agreement immediately upon notice if You breach any term of this
+   Agreement. Upon termination, You must cease all use of the SDK and
+   destroy all copies in Your possession or control. Sections 3, 4, 7,
+   8, and 9 survive termination.
+
+7. Disclaimer of Warranty
+   THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE" WITHOUT WARRANTY OF
+   ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+   WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
+   TITLE, AND NON-INFRINGEMENT. axonkit DOES NOT WARRANT THAT THE SDK
+   WILL BE ERROR-FREE OR UNINTERRUPTED.
+
+8. Limitation of Liability
+   TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
+   axonkit OR ITS AFFILIATES BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
+   SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES, OR ANY LOSS OF PROFITS,
+   REVENUE, DATA, OR USE, ARISING OUT OF OR IN CONNECTION WITH THIS
+   AGREEMENT OR THE SDK, WHETHER IN CONTRACT, TORT, OR OTHERWISE, EVEN
+   IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+9. Governing Law
+   This Agreement shall be governed by and construed in accordance with
+   applicable laws, without regard to its conflict of law provisions.
+
+10. Entire Agreement
+    This Agreement constitutes the entire agreement between You and
+    axonkit regarding the SDK and supersedes all prior or contemporaneous
+    understandings.
+
+For licensing inquiries, please contact: <jiyeyuran@gmail.com>

package/README.md

@@ -0,0 +1,125 @@
+# @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>.
+
+## Installation
+
+```bash
+pnpm add @axonkit/client-sdk-js
+```
+
+## Quick Start
+
+```typescript
+import { Room, RoomState, setLogLevel, LogLevel } from '@axonkit/client-sdk-js';
+
+setLogLevel(LogLevel.INFO);
+
+const room = new Room({
+  autoSubscribe: true,
+  dynacast: true,
+  adaptiveStream: true,
+});
+
+// Connect
+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
+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
+
+## API Reference
+
+### Room
+
+| Method                | Description                                |
+| --------------------- | ------------------------------------------ |
+| `connect(url, token)` | Connect to a room                          |
+| `disconnect()`        | Disconnect from the room                   |
+| `startAudio()`        | Start audio playback (for 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     |
+
+### Events
+
+```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) => {});
+```
+
+## Building
+
+```bash
+pnpm install
+pnpm build
+```
+
+Outputs:
+
+- `dist/axonkit-client.esm.js` — ES Module
+- `dist/axonkit-client.umd.js` — UMD (for `<script>` tags)
+- `dist/index.d.ts` — TypeScript declarations
+
+## Demo
+
+Open `examples/demo/index.html` in a browser after building. Requires a running AxonKit server.
+
+## License
+
+MIT

package/dist/Room.d.ts

@@ -0,0 +1,273 @@
+import { TypedEmitter } from './utils/typedEmitter';
+import { LocalParticipant } from './participant/LocalParticipant';
+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 type { RoomOptions, RoomConnectOptions } from './room/options';
+import { Track } from './track/Track';
+import { RoomEvent } from './events';
+import type { Message, RpcInvocationData, TextStreamHandler, ByteStreamHandler } from './types';
+export type RoomEvents = {
+    [RoomEvent.Connected]: () => void;
+    [RoomEvent.Disconnected]: (reason?: DisconnectReason) => void;
+    [RoomEvent.Reconnecting]: () => void;
+    [RoomEvent.Reconnected]: () => void;
+    [RoomEvent.ConnectionStateChanged]: (state: RoomState) => 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.ParticipantUpdated]: (participant: RemoteParticipant) => void;
+    [RoomEvent.ParticipantMetadataChanged]: (prevMetadata: string | undefined, participant: Participant) => void;
+    [RoomEvent.ParticipantNameChanged]: (name: string, participant: Participant) => void;
+    [RoomEvent.ParticipantAttributesChanged]: (changed: Record<string, string>, participant: Participant) => void;
+    [RoomEvent.TrackPublished]: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
+    [RoomEvent.TrackUnpublished]: (publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
+    [RoomEvent.TrackSubscribed]: (track: Track, publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
+    [RoomEvent.TrackSubscriptionFailed]: (trackSid: string, participant: RemoteParticipant) => void;
+    [RoomEvent.TrackUnsubscribed]: (track: Track, publication: RemoteTrackPublication, participant: RemoteParticipant) => void;
+    [RoomEvent.TrackMuted]: (publication: LocalTrackPublication | RemoteTrackPublication, participant: Participant) => void;
+    [RoomEvent.TrackUnmuted]: (publication: LocalTrackPublication | RemoteTrackPublication, participant: Participant) => void;
+    [RoomEvent.LocalTrackPublished]: (publication: LocalTrackPublication, participant: LocalParticipant) => void;
+    [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.ConnectionQualityChanged]: (quality: ConnectionQuality, participant: Participant) => void;
+    [RoomEvent.AudioPlaybackStatusChanged]: (canPlayback: boolean) => void;
+    [RoomEvent.VideoPlaybackStatusChanged]: (canPlayback: boolean) => 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;
+    [RoomEvent.StateDeleted]: (key: string, participantSid?: string, participantIdentity?: string) => void;
+    [RoomEvent.TrackStreamStateChanged]: (publication: RemoteTrackPublication, streamState: StreamState, participant: RemoteParticipant) => void;
+    [RoomEvent.GroupCreated]: (group: GroupInfo) => void;
+    [RoomEvent.GroupUpdated]: (group: GroupInfo) => void;
+    [RoomEvent.GroupDeleted]: (groupId: string) => void;
+    [RoomEvent.GroupParticipantJoined]: (groupId: string, participant: Participant) => void;
+    [RoomEvent.GroupParticipantLeft]: (groupId: string, participant: Participant) => void;
+    [RoomEvent.TokenRefreshed]: (token: string) => void;
+};
+export declare class Room extends TypedEmitter<RoomEvents> {
+    private _state;
+    private _name;
+    private _sid;
+    private _serverInfo?;
+    private _roomInfo?;
+    private _options;
+    private url;
+    private token;
+    private _refreshToken;
+    private nodeId;
+    private participantSid;
+    private signalClient;
+    private rpcClient;
+    private transportManager;
+    private _localParticipant;
+    private _remoteParticipants;
+    private _groups;
+    private _sharedState;
+    private pingInterval?;
+    private pingTimeoutTimer?;
+    private pingIntervalSec;
+    private pingTimeoutSec;
+    private lastRtt;
+    private reconnectAttempts;
+    private reconnectPolicy;
+    private statsCollector?;
+    private pageLeaveHandler?;
+    private deviceChangeHandler?;
+    private _canPlaybackAudio;
+    private _canPlaybackVideo;
+    private _activeDeviceMap;
+    private dataStreamReceiver;
+    private _lastMessageTimestamp;
+    private _connectOptions;
+    constructor(options?: RoomOptions);
+    get state(): RoomState;
+    get name(): string;
+    get sid(): string;
+    get serverInfo(): ServerInfo | undefined;
+    get localParticipant(): LocalParticipant;
+    get remoteParticipants(): Map<string, RemoteParticipant>;
+    /**
+     * Returns WebRTC stats for the underlying send and receive transports.
+     */
+    getTransportStats(): Promise<{
+        send?: RTCStatsReport;
+        recv?: RTCStatsReport;
+    }>;
+    /** All active groups (breakout rooms) in this room. */
+    get groups(): ReadonlyMap<string, GroupInfo>;
+    /** Room-level shared state KV (for collaboration features like whiteboard, shared documents). */
+    get sharedState(): ReadonlyMap<string, string>;
+    /**
+     * Get all participants currently in the specified group.
+     * Includes the local participant if they are in the group.
+     */
+    getGroupParticipants(groupId: string): Participant[];
+    /**
+     * Get all participants.
+     */
+    getParticipants(): Participant[];
+    /** Whether audio can be played back automatically (i.e. no autoplay restriction). */
+    get canPlaybackAudio(): boolean;
+    /** Whether video can be played back automatically. */
+    get canPlaybackVideo(): boolean;
+    /** Whether the room is currently being recorded. */
+    get isRecording(): boolean;
+    /** Room-level metadata (set by the server). */
+    get metadata(): string | undefined;
+    /** Number of participants currently in the room. */
+    get numParticipants(): number;
+    /** Number of participants that are actively publishing tracks. */
+    get numPublishers(): number;
+    /** List of participants currently speaking, ordered by audio level. */
+    get activeSpeakers(): Participant[];
+    /**
+     * Look up a remote participant by their identity.
+     */
+    getParticipantByIdentity(identity: string): RemoteParticipant | undefined;
+    /** Find any participant (local or remote) by SID. */
+    private getParticipantBySid;
+    /**
+     * Create a new group (breakout room) within this room.
+     * Requires `canManageGroups` permission.
+     */
+    createGroup(name: string, permissions?: import('./protocol/types').ParticipantPermission): Promise<GroupInfo>;
+    /**
+     * Delete a group. All participants in the group are returned to the main room
+     * and their permissions revert to room-level defaults.
+     * Requires `canManageGroups` permission.
+     */
+    deleteGroup(groupId: string): Promise<void>;
+    /**
+     * List all active groups in this room.
+     */
+    listGroups(): Promise<GroupInfo[]>;
+    /**
+     * Pin a remote participant so their media tracks are always received,
+     * regardless of active speaker rotation. Pinned participants occupy
+     * lastN slots with highest priority.
+     */
+    pinParticipant(participantSid: string): Promise<void>;
+    /**
+     * Unpin a previously pinned participant. Their media subscription will
+     * then be subject to active speaker rotation under lastN rules.
+     */
+    unpinParticipant(participantSid: string): Promise<void>;
+    /**
+     * Enumerate available media input/output devices.
+     * @param kind - Filter by device kind. If omitted, all devices are returned.
+     */
+    static getLocalDevices(kind?: MediaDeviceKind): Promise<MediaDeviceInfo[]>;
+    /**
+     * Switch the active device for a given kind across all published tracks.
+     * @param kind - `videoinput`, `audioinput`, or `audiooutput`.
+     * @param deviceId - The device ID to switch to.
+     * @param exact - If `true`, sets the `deviceId` constraint to `exact`.
+     *   Defaults to `true`.
+     */
+    switchActiveDevice(kind: MediaDeviceKind, deviceId: string, exact?: boolean): Promise<void>;
+    connect(url: string, token?: string, options?: RoomConnectOptions): Promise<void>;
+    private performConnect;
+    /**
+     * Disconnect from the room.
+     * @param stopTracks - Whether to stop local tracks after disconnecting.
+     *   Defaults to `true`.
+     */
+    disconnect(stopTracks?: boolean): Promise<void>;
+    private attemptReconnect;
+    private performReconnect;
+    private withTimeout;
+    private buildSyncState;
+    private setState;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private sendPing;
+    get rtt(): number;
+    private startStatsCollector;
+    private stopStatsCollector;
+    /**
+     * Attempt to start audio playback on all remote audio tracks.
+     * Should be called from a user interaction handler when
+     * `canPlaybackAudio` is `false`.
+     */
+    startAudio(): Promise<void>;
+    /**
+     * Attempt to start video playback on all remote video tracks.
+     * Should be called from a user interaction handler when
+     * `canPlaybackVideo` is `false`.
+     */
+    startVideo(): Promise<void>;
+    /**
+     * Returns the device ID currently active for a given kind, if known.
+     */
+    getActiveDevice(kind: MediaDeviceKind): string | undefined;
+    /**
+     * Register an RPC method handler. When a remote participant calls
+     * `performRpc` with the given method name, the handler is invoked.
+     *
+     * @param method - Method name to handle.
+     * @param handler - Async function that receives invocation data and returns
+     *   a string payload.
+     */
+    registerRpcMethod(method: string, handler: (data: RpcInvocationData) => Promise<string>): void;
+    /**
+     * Remove a previously registered RPC method handler.
+     */
+    unregisterRpcMethod(method: string): void;
+    /**
+     * Register a handler for incoming text streams on a specific topic.
+     */
+    registerTextStreamHandler(topic: string, handler: TextStreamHandler): void;
+    /**
+     * Unregister a previously registered text stream handler.
+     */
+    unregisterTextStreamHandler(topic: string): void;
+    /**
+     * Register a handler for incoming byte streams on a specific topic.
+     */
+    registerByteStreamHandler(topic: string, handler: ByteStreamHandler): void;
+    /**
+     * Unregister a previously registered byte stream handler.
+     */
+    unregisterByteStreamHandler(topic: string): void;
+    private applyJoinResponse;
+    private registerRPCHandlers;
+    private registerNotificationHandlers;
+    private applyReadySnapshot;
+    private replaceRemoteParticipants;
+    private replaceGroups;
+    private replaceSharedState;
+    private upsertRemoteParticipant;
+    private scheduleReadySnapshotReplay;
+    private handleParticipantJoined;
+    private handleParticipantLeft;
+    private handleParticipantUpdated;
+    private handleTrackPublished;
+    private handleTrackUnpublished;
+    private handleDataTrackPublished;
+    private handleDataTrackUnpublished;
+    private handleTrackMuted;
+    /** Video dynacast: per-layer quality change + producer pause/resume. */
+    private handleSubscribedQualityChanged;
+    private handleActiveSpeakersChanged;
+    private handleMessage;
+    private handleRoomUpdated;
+    private handleDisconnect;
+    private handleSubscriptionCreate;
+    private handleDataSubscriptionCreate;
+    private handleSubscriptionClosed;
+    private handleDataSubscriptionClosed;
+    private wireRemoteParticipantEvents;
+    private wireLocalParticipantEvents;
+    private setupDeviceChangeListener;
+    private cleanup;
+    private wireTransportEvents;
+    private setupPageLeaveHandler;
+}