@axonkit/client-sdk-js 0.1.0

package/dist/participant/LocalParticipant.d.ts

@@ -0,0 +1,186 @@
+import { Participant } from './Participant';
+import { LocalTrackPublication } from './LocalTrackPublication';
+import { LocalTrack } from '../track/LocalTrack';
+import type { ParticipantTrackPermission, ParticipantInfo } from '../protocol/types';
+import type { TrackPublishOptions, DataPublishOptions, AudioCaptureOptions, VideoCaptureOptions, ScreenShareCaptureOptions } from '../track/options';
+import type { RoomOptions } from '../room/options';
+import type { Message, SendTextOptions, StreamTextOptions, StreamBytesOptions, SendFileOptions, PerformRpcParams } from '../types';
+import { TextStreamWriter, ByteStreamWriter } from '../data-stream/DataStreamManager';
+export declare class LocalParticipant extends Participant<LocalTrackPublication> {
+    private rpc;
+    private transportManager;
+    private producers;
+    private dataProducers;
+    private dataStreamSender?;
+    private _lastCameraError?;
+    private _lastMicrophoneError?;
+    private participantTrackPermissions;
+    private allParticipantsAllowedToSubscribe;
+    /** Room-level options passed in from the Room instance. */
+    roomOptions?: RoomOptions;
+    get isLocal(): boolean;
+    /** Last error encountered while creating a camera track. */
+    get lastCameraError(): Error | undefined;
+    /** Last error encountered while creating a microphone track. */
+    get lastMicrophoneError(): Error | undefined;
+    setCameraEnabled(enabled: boolean, captureOptions?: VideoCaptureOptions, publishOptions?: TrackPublishOptions): Promise<LocalTrackPublication | undefined>;
+    setMicrophoneEnabled(enabled: boolean, captureOptions?: AudioCaptureOptions, publishOptions?: TrackPublishOptions): Promise<LocalTrackPublication | undefined>;
+    setScreenShareEnabled(enabled: boolean, captureOptions?: ScreenShareCaptureOptions, publishOptions?: TrackPublishOptions): Promise<LocalTrackPublication | undefined>;
+    /**
+     * Enable both camera and microphone simultaneously.
+     * Uses a single `getUserMedia` call so the user only grants permission once.
+     */
+    enableCameraAndMicrophone(captureOptions?: {
+        audio?: AudioCaptureOptions;
+        video?: VideoCaptureOptions;
+    }, publishOptions?: TrackPublishOptions): Promise<void>;
+    publishTrack(track: LocalTrack | MediaStreamTrack, options?: TrackPublishOptions): Promise<LocalTrackPublication>;
+    /**
+     * Unpublish a track from the room.
+     * @param track - The track or MediaStreamTrack to unpublish.
+     * @param stopOnUnpublish - Whether to stop the track after unpublishing.
+     *   Defaults to `false`.
+     */
+    unpublishTrack(track: LocalTrack | MediaStreamTrack): Promise<LocalTrackPublication | undefined>;
+    publishData(data: Uint8Array, options?: DataPublishOptions): Promise<void>;
+    /**
+     * Sets and updates the metadata of the local participant.
+     * Note: this requires `canUpdateMetadata` permission.
+     */
+    setMetadata(metadata: string): Promise<void>;
+    /**
+     * Sets and updates the name of the local participant.
+     * Note: this requires `canUpdateMetadata` permission.
+     */
+    setName(name: string): Promise<void>;
+    /**
+     * Set or update participant attributes. It will make updates only to keys that
+     * are present in `attributes`, and will not override others.
+     * Note: this requires `canUpdateMetadata` permission.
+     */
+    setAttributes(attributes: Record<string, string>): Promise<void>;
+    /**
+     * Join a group (breakout room). The server will rewire subscriptions
+     * so that only participants in the same group exchange media.
+     * Permissions may change to the group-level permissions.
+     * @returns The list of other participants already in the group.
+     */
+    joinGroup(groupId: string): Promise<ParticipantInfo[]>;
+    /**
+     * Leave the current group and return to the main room.
+     * Permissions revert to room-level defaults.
+     */
+    leaveGroup(): Promise<void>;
+    /**
+     * Control who can subscribe to LocalParticipant's published tracks.
+     *
+     * By default, all participants can subscribe. This allows fine-grained control over
+     * who is able to subscribe at a participant and track level.
+     *
+     * @param allParticipantsAllowed - Allows all participants to subscribe all tracks.
+     *   Takes precedence over `participantTrackPermissions` if set to true.
+     * @param participantTrackPermissions - Full list of individual permissions per
+     *   participant/track. Any omitted participants will not receive any permissions.
+     */
+    setTrackSubscriptionPermissions(allParticipantsAllowed: boolean, participantTrackPermissions?: ParticipantTrackPermission[]): void;
+    private updateTrackSubscriptionPermissions;
+    /**
+     * Send a message to all participants in the room.
+     * @param text - The message text / payload.
+     * @param options - Optional settings such as `type`, `transient`, `topic`, etc.
+     */
+    sendMessage(text: string, options?: SendTextOptions & {
+        type?: string;
+        transient?: boolean;
+    }): Promise<Message>;
+    /**
+     * Edit a previously sent message.
+     */
+    editMessage(editText: string, originalMessage: Message): Promise<Message>;
+    /**
+     * Delete a single message by ID.
+     */
+    deleteMessage(id: string): Promise<void>;
+    /**
+     * Delete all messages of a given type.
+     */
+    deleteMessagesByType(type: string): Promise<void>;
+    /**
+     * Update a key in the room's shared state.
+     */
+    updateRoomState(key: string, value: string): Promise<void>;
+    /**
+     * Delete a key from the room's shared state.
+     */
+    deleteRoomState(key: string): Promise<void>;
+    /** @deprecated Use {@link sendMessage} instead. */
+    sendChatMessage(text: string, options?: SendTextOptions): Promise<Message>;
+    /** @deprecated Use {@link editMessage} instead. */
+    editChatMessage(editText: string, originalMessage: Message): Promise<Message>;
+    /**
+     * Send a complete text message to participants via data stream.
+     */
+    sendText(text: string, options?: SendTextOptions): Promise<{
+        id: string;
+    }>;
+    /**
+     * Open an incremental text stream to participants.
+     * Returns a writer that can be used to send text chunks.
+     */
+    streamText(options?: StreamTextOptions): Promise<TextStreamWriter>;
+    /**
+     * Send a file to participants via data stream.
+     */
+    sendFile(file: File, options?: SendFileOptions): Promise<{
+        id: string;
+    }>;
+    /**
+     * Open an incremental byte stream to participants.
+     * Returns a writer that can be used to send byte chunks.
+     */
+    streamBytes(options?: StreamBytesOptions): Promise<ByteStreamWriter>;
+    /**
+     * Perform an RPC call to a specific remote participant.
+     * The remote participant must have registered a handler for the method
+     * via `room.registerRpcMethod`.
+     *
+     * @returns The response payload string.
+     */
+    performRpc(params: PerformRpcParams): Promise<string>;
+    private buildCodecOptions;
+    /**
+     * Unpublish all tracks matching the given sources, or all tracks if no sources specified.
+     */
+    unpublishTracks(tracks: LocalTrack[]): Promise<void>;
+    /**
+     * Create local tracks without publishing. Useful for creating preview tracks.
+     */
+    createTracks(options?: {
+        audio?: AudioCaptureOptions | boolean;
+        video?: VideoCaptureOptions | boolean;
+    }): Promise<LocalTrack[]>;
+    /**
+     * Create screen share tracks without publishing.
+     */
+    createScreenTracks(options?: ScreenShareCaptureOptions): Promise<LocalTrack[]>;
+    /**
+     * Re-publish all currently published tracks. Useful after a full reconnect
+     * or when changing publish options globally.
+     *
+     * The transportclose handler only clears `producers`, not
+     * `trackPublications`, so the publications are still available here even
+     * after the old transport has been closed.
+     */
+    republishAllTracks(options?: TrackPublishOptions, restartTracks?: boolean): Promise<void>;
+    /**
+     * Creates a second producer for the backup codec on an already-published
+     * video track. The new producer is registered on the server via
+     * `track.publishBackup` RPC.
+     */
+    private publishAdditionalCodecForTrack;
+}
+/**
+ * Resolves the backup codec string from publish options.
+ * Returns the backup codec name or undefined if no backup is configured.
+ */
+export declare function resolveBackupCodec(opts: TrackPublishOptions): string | undefined;

package/dist/participant/LocalTrackPublication.d.ts

@@ -0,0 +1,28 @@
+import { TrackPublication } from './Participant';
+import { AudioTrackFeature } from '../protocol/types';
+import type { TrackPublishOptions } from '../track/options';
+export declare class LocalTrackPublication extends TrackPublication {
+    /** The options used when publishing the track. */
+    options?: TrackPublishOptions;
+    get isLocal(): boolean;
+    get isMuted(): boolean;
+    /** Whether upstream publishing is paused for this track. */
+    get isUpstreamPaused(): boolean;
+    /** Mute the track associated with this publication. */
+    mute(): void;
+    /** Unmute the track associated with this publication. */
+    unmute(): void;
+    /**
+     * Pause publishing to the server without disabling the local MediaStreamTrack.
+     */
+    pauseUpstream(): Promise<void>;
+    /**
+     * Resume publishing after a call to {@link pauseUpstream}.
+     */
+    resumeUpstream(): Promise<void>;
+    /**
+     * Returns a list of audio track features detected from the current track settings.
+     * Only applicable to audio tracks.
+     */
+    getTrackFeatures(): AudioTrackFeature[];
+}

package/dist/participant/Participant.d.ts

@@ -0,0 +1,133 @@
+import { TypedEmitter } from '../utils/typedEmitter';
+import type { ParticipantInfo, ParticipantPermission, TrackInfo, TrackSource } from '../protocol/types';
+import { ConnectionQuality, ParticipantState, ParticipantKind, StreamState } from '../protocol/types';
+import type { Track } from '../track/Track';
+import type { LocalAudioTrack } from '../track/LocalAudioTrack';
+import type { LocalVideoTrack } from '../track/LocalVideoTrack';
+import type { RemoteAudioTrack } from '../track/RemoteAudioTrack';
+import type { RemoteVideoTrack } from '../track/RemoteVideoTrack';
+import { ParticipantEvent } from '../events';
+import type { Message } from '../types';
+/**
+ * Subscription status for a remote track publication.
+ */
+export declare enum SubscriptionStatus {
+    /** The track is desired but not yet subscribed. */
+    Desired = "desired",
+    /** The track is subscribed and a {@link Track} is available. */
+    Subscribed = "subscribed",
+    /** The track is not subscribed. */
+    Unsubscribed = "unsubscribed"
+}
+export declare class TrackPublication {
+    trackSid: string;
+    trackName: string;
+    kind: string;
+    source: TrackSource;
+    track?: Track;
+    muted: boolean;
+    info?: TrackInfo;
+    /** MIME type of the track (e.g. `video/VP8`, `audio/opus`). */
+    mimeType?: string;
+    /** Whether the track was published with simulcast. */
+    simulcasted?: boolean;
+    /** Original video dimensions from the publisher. */
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    constructor(init: {
+        trackSid: string;
+        trackName: string;
+        kind: string;
+        source: TrackSource;
+        track?: Track;
+        muted: boolean;
+        info?: TrackInfo;
+    });
+    /** Whether the track is subscribed (i.e. a concrete {@link Track} is available). */
+    get isSubscribed(): boolean;
+    /** Whether the track is enabled (not muted). */
+    get isEnabled(): boolean;
+    /** Whether the track is muted. */
+    get isMuted(): boolean;
+    /** Type-safe audio track getter. Returns `undefined` if the track is video. */
+    get audioTrack(): LocalAudioTrack | RemoteAudioTrack | undefined;
+    /** Type-safe video track getter. Returns `undefined` if the track is audio. */
+    get videoTrack(): LocalVideoTrack | RemoteVideoTrack | undefined;
+    /** Whether this publication belongs to the local participant. */
+    get isLocal(): boolean;
+}
+export type ParticipantEvents<TPublication extends TrackPublication = TrackPublication> = {
+    [ParticipantEvent.TrackPublished]: (publication: TPublication) => void;
+    [ParticipantEvent.TrackUnpublished]: (publication: TPublication) => void;
+    [ParticipantEvent.TrackMuted]: (publication: TPublication) => void;
+    [ParticipantEvent.TrackUnmuted]: (publication: TPublication) => void;
+    [ParticipantEvent.TrackSubscribed]: (track: Track, publication: TPublication) => void;
+    [ParticipantEvent.TrackUnsubscribed]: (track: Track, publication: TPublication) => void;
+    [ParticipantEvent.LocalTrackPublished]: (publication: TPublication) => void;
+    [ParticipantEvent.LocalTrackUnpublished]: (publication: TPublication) => void;
+    [ParticipantEvent.MetadataChanged]: (metadata: string | undefined, participant: Participant<TPublication>) => void;
+    [ParticipantEvent.NameChanged]: (name: string | undefined, participant: Participant<TPublication>) => void;
+    [ParticipantEvent.AttributesChanged]: (changedAttributes: Record<string, string>, participant: Participant<TPublication>) => void;
+    [ParticipantEvent.IsSpeakingChanged]: (speaking: boolean) => void;
+    [ParticipantEvent.ConnectionQualityChanged]: (quality: ConnectionQuality) => void;
+    [ParticipantEvent.PermissionsChanged]: (prevPermissions?: ParticipantPermission) => void;
+    [ParticipantEvent.TrackStreamStateChanged]: (publication: TPublication, streamState: StreamState) => void;
+    [ParticipantEvent.DataReceived]: (data: ArrayBuffer) => void;
+    [ParticipantEvent.ChatMessage]: (message: Message) => void;
+};
+export declare abstract class Participant<TPublication extends TrackPublication = TrackPublication> extends TypedEmitter<ParticipantEvents<TPublication>> {
+    sid: string;
+    identity: string;
+    name?: string;
+    metadata?: string;
+    state: ParticipantState;
+    isSpeaking: boolean;
+    audioLevel: number;
+    attributes: Record<string, string>;
+    permissions?: ParticipantPermission;
+    /** The group (breakout room) this participant is currently in. `undefined` = main room. */
+    groupId?: string;
+    trackPublications: Map<string, TPublication>;
+    audioTrackPublications: Map<string, TPublication>;
+    videoTrackPublications: Map<string, TPublication>;
+    lastSpokeAt?: Date;
+    joinedAt?: Date;
+    private _connectionQuality;
+    private _kind;
+    private _activeResolvers;
+    private emitParticipantEvent;
+    constructor(sid: string, identity: string, name?: string, metadata?: string);
+    abstract get isLocal(): boolean;
+    /** The kind of participant (Standard, Agent, etc.). */
+    get kind(): ParticipantKind;
+    /** Whether this participant is an AI agent. */
+    get isAgent(): boolean;
+    /** Whether the participant is in an active (joined) state. */
+    get isActive(): boolean;
+    /**
+     * Returns a promise that resolves once the participant is active
+     * and ready to receive data messages.
+     */
+    waitUntilActive(): Promise<void>;
+    /** Current connection quality for this participant. */
+    get connectionQuality(): ConnectionQuality;
+    /** Whether the participant has an enabled camera track. */
+    get isCameraEnabled(): boolean;
+    /** Whether the participant has an enabled microphone track. */
+    get isMicrophoneEnabled(): boolean;
+    /** Whether the participant is sharing their screen. */
+    get isScreenShareEnabled(): boolean;
+    /**
+     * Returns all track publications as an array.
+     */
+    getTrackPublications(): TPublication[];
+    updateFromInfo(info: ParticipantInfo): void;
+    getTrackPublication(source: TrackSource): TPublication | undefined;
+    /**
+     * Find a track publication by its name.
+     */
+    getTrackPublicationByName(name: string): TPublication | undefined;
+    private isTrackEnabled;
+}

package/dist/participant/RemoteParticipant.d.ts

@@ -0,0 +1,30 @@
+import { Participant } from './Participant';
+import { RemoteTrackPublication } from './RemoteTrackPublication';
+import { TransportManager } from '../transport/TransportManager';
+import { RPCClient } from '../signal/RPCClient';
+import { type DataStreamReceiver } from '../data-stream/DataStreamManager';
+export interface RemoteParticipantOptions {
+    transportManager: TransportManager;
+    rpc: RPCClient;
+    autoSubscribe?: boolean;
+    streamReceiver?: DataStreamReceiver;
+}
+export declare class RemoteParticipant extends Participant<RemoteTrackPublication> {
+    private transportManager;
+    private rpc;
+    private consumers;
+    private dataConsumers;
+    private streamReceiver?;
+    private autoSubscribe;
+    get isLocal(): boolean;
+    /**
+     * Set the output volume for all audio tracks from this participant.
+     * @param volume - Value between 0 and 1.
+     */
+    setVolume(volume: number): void;
+    /**
+     * Get the current output volume for this participant's audio tracks.
+     * Returns the volume of the first audio track, or 1 if none.
+     */
+    getVolume(): number;
+}

package/dist/participant/RemoteTrackPublication.d.ts

@@ -0,0 +1,63 @@
+import { TrackPublication, SubscriptionStatus } from './Participant';
+import { VideoQuality, StreamState } from '../protocol/types';
+export declare class RemoteTrackPublication extends TrackPublication {
+    streamState: StreamState;
+    private _consumer?;
+    private _rpc?;
+    private _subscribed;
+    private _videoQuality?;
+    private _enabled;
+    private _fps?;
+    private _requestedVideoDimensions?;
+    /** Whether this track is currently subscribed. */
+    get isSubscribed(): boolean;
+    /** Returns `true` if the client wants to subscribe to this track. */
+    get isDesired(): boolean;
+    /** Current subscription status. */
+    get subscriptionStatus(): SubscriptionStatus;
+    /** The currently requested video quality. */
+    get videoQuality(): VideoQuality | undefined;
+    /** Whether the server is enabled to send data for this track. */
+    get isEnabled(): boolean;
+    /**
+     * Enable or disable the server from sending data for this track.
+     * Useful when a track is off-screen.
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Control whether the subscription for this track is desired.
+     * When set to `false`, the server will stop sending media for this track.
+     */
+    setSubscribed(subscribed: boolean): void;
+    /**
+     * Set the preferred video quality for this subscription.
+     * Only applicable to video tracks.
+     */
+    setVideoQuality(quality: VideoQuality): void;
+    /**
+     * Explicitly set the desired video dimensions for this track.
+     * Maps to spatialLayer using {@link TrackInfo} width/height as the high layer
+     * and typical simulcast factors (1/2, 1/4) when layer metadata is not on the wire.
+     */
+    setVideoDimensions(dimensions: {
+        width: number;
+        height: number;
+    }): void;
+    /**
+     * Set the desired video FPS for this subscription.
+     * In simulcast and SVC scenarios, fps controls the temporal layer.
+     */
+    setVideoFPS(fps: number): void;
+    private isManualOperationAllowed;
+    /**
+     * Sends the current preferred layers to the server.
+     * Computes spatialLayer from videoQuality or dimensions, and temporalLayer from fps.
+     */
+    private emitTrackUpdate;
+    /**
+     * Pick the smallest spatial layer whose notional size covers the request.
+     * Uses published track dimensions as the full layer; derives low/medium like
+     * LiveKit's videoLayersFromEncodings (ceil half / quarter) when only width/height exist.
+     */
+    private spatialLayerForDimensions;
+}

package/dist/protocol/errors.d.ts

@@ -0,0 +1,22 @@
+export declare enum ErrorCode {
+    OK = 200,
+    BadRequest = 400,
+    Unauthorized = 401,
+    Forbidden = 403,
+    NotFound = 404,
+    Conflict = 409,
+    InternalError = 500
+}
+export declare class AxonError extends Error {
+    code: ErrorCode;
+    logId?: string;
+    constructor(code: ErrorCode, message: string, logId?: string);
+    static fromStatus(status: number, message: string, logId?: string): AxonError;
+}
+export declare class ConnectionError extends Error {
+    status?: number;
+    constructor(message: string, status?: number);
+}
+export declare class TimeoutError extends Error {
+    constructor(message?: string);
+}

package/dist/protocol/message.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Axon Protocol message encoder/decoder.
+ *
+ * Wire format (text-based, binary-safe body):
+ *   Request:      REQ <method> <logId>\r\n[headers]\r\n<body>
+ *   Response:     RES <logId> <status>\r\n[headers]\r\n<body>
+ *   Notification: MSG <method> [<logId>]\r\n[headers]\r\n<body>
+ *
+ * Optional headers block:
+ *   AXON/1.0\r\n
+ *   Key: Value\r\n
+ *   \r\n
+ */
+export declare enum MessageType {
+    REQ = "REQ",
+    RES = "RES",
+    MSG = "MSG"
+}
+export interface AxonMessage {
+    type: MessageType;
+    method?: string;
+    logId?: string;
+    status?: number;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+}
+export declare function encode(msg: AxonMessage): Uint8Array;
+export declare function decode(data: Uint8Array | ArrayBuffer): AxonMessage;
+export declare function bodyToJSON<T = any>(msg: AxonMessage): T | undefined;
+export declare function jsonToBody(obj: any): Uint8Array;