@axonkit/client-sdk-js 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,146 @@
+/**
+ * A message exchanged between participants (chat, whiteboard, document, etc.).
+ */
+export interface Message {
+    /** Unique message identifier. */
+    id: string;
+    /** Message type: "text", "whiteboard", "document", "image", "video", "audio", "file", "system", etc. */
+    type?: string;
+    /** Unix timestamp in milliseconds when the message was sent. */
+    timestamp: number;
+    /** The text content of the message. */
+    message: string;
+    /** Unix timestamp in milliseconds of the last edit, if edited. */
+    editTimestamp?: number;
+    /** If true, the message is not persisted (e.g. mouse coordinates). */
+    transient?: boolean;
+    /** Optional file attachment identifiers. */
+    attachedFiles?: string[];
+}
+/** @deprecated Use {@link Message} instead. */
+export type ChatMessage = Message;
+/**
+ * Options when sending a text message.
+ */
+export interface SendTextOptions {
+    /** Topic identifier used to route the message to appropriate handlers. */
+    topic?: string;
+    /** Participant identities to send to. If empty, sends to all. */
+    destinationIdentities?: string[];
+    /** Optional file attachment identifiers. */
+    attachments?: string[];
+    /** Progress callback (0–1). */
+    onProgress?: (progress: number) => void;
+    /** Key-value attributes attached to the stream. */
+    attributes?: Record<string, string>;
+}
+/**
+ * Options when opening an incremental text stream.
+ */
+export interface StreamTextOptions {
+    /** Topic identifier. */
+    topic?: string;
+    /** Participant identities to send to. If empty, sends to all. */
+    destinationIdentities?: string[];
+    /** Key-value attributes attached to the stream. */
+    attributes?: Record<string, string>;
+    /** Total size in bytes if known ahead of time. */
+    totalSize?: number;
+}
+/**
+ * Options when streaming raw bytes.
+ */
+export interface StreamBytesOptions {
+    /** Human-readable name for the stream. */
+    name?: string;
+    /** Topic identifier. */
+    topic?: string;
+    /** MIME type of the data. */
+    mimeType?: string;
+    /** Key-value attributes attached to the stream. */
+    attributes?: Record<string, string>;
+    /** Participant identities to send to. If empty, sends to all. */
+    destinationIdentities?: string[];
+    /** Total size in bytes if known ahead of time. */
+    totalSize?: number;
+}
+/**
+ * Options when sending a file.
+ */
+export interface SendFileOptions {
+    /** Topic identifier. */
+    topic?: string;
+    /** MIME type override. If omitted, derived from the File object. */
+    mimeType?: string;
+    /** Participant identities to send to. */
+    destinationIdentities?: string[];
+    /** Progress callback (0–1). */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * Base information about an incoming data stream.
+ */
+export interface BaseStreamInfo {
+    id: string;
+    mimeType: string;
+    topic: string;
+    timestamp: number;
+    /** Total size in bytes for finite streams, `undefined` for unknown-size streams. */
+    size?: number;
+    attributes?: Record<string, string>;
+}
+/**
+ * Information about an incoming byte stream.
+ */
+export interface ByteStreamInfo extends BaseStreamInfo {
+    name: string;
+}
+/**
+ * Information about an incoming text stream.
+ */
+export type TextStreamInfo = BaseStreamInfo;
+/**
+ * Identifies the participant who sent a data stream.
+ */
+export interface StreamSenderInfo {
+    identity: string;
+    sid: string;
+}
+import type { TextStreamReader, ByteStreamReader } from './data-stream/DataStreamManager';
+/**
+ * Handler called when an incoming text stream is received on a registered topic.
+ */
+export type TextStreamHandler = (reader: TextStreamReader, sender: StreamSenderInfo) => void;
+/**
+ * Handler called when an incoming byte stream is received on a registered topic.
+ */
+export type ByteStreamHandler = (reader: ByteStreamReader, sender: StreamSenderInfo) => void;
+/**
+ * Parameters for initiating a P2P RPC call.
+ */
+export interface PerformRpcParams {
+    /** The `identity` of the destination participant. */
+    destinationIdentity: string;
+    /** The method name to call. */
+    method: string;
+    /** The method payload (typically JSON string). */
+    payload: string;
+    /**
+     * Timeout for receiving a response (milliseconds).
+     * @defaultValue 15000
+     */
+    responseTimeout?: number;
+}
+/**
+ * Data passed to an RPC method handler.
+ */
+export interface RpcInvocationData {
+    /** The unique request ID. */
+    requestId: string;
+    /** The identity of the caller. */
+    callerIdentity: string;
+    /** The payload of the request. */
+    payload: string;
+    /** The maximum time the caller will wait for a response. */
+    responseTimeout: number;
+}

package/dist/utils/browser.d.ts

@@ -0,0 +1,113 @@
+import type { LocalTrack } from '../track/LocalTrack';
+import type { Track } from '../track/Track';
+/**
+ * Details about the current browser.
+ */
+export interface BrowserDetails {
+    name: string;
+    version: string;
+    os?: string;
+    osVersion?: string;
+    supportsInsertableStreams: boolean;
+    supportsTransceiver: boolean;
+}
+/**
+ * Options for creating an audio analyser.
+ */
+export interface AudioAnalyserOptions {
+    /**
+     * FFT size for the analyser node. Must be a power of 2 between 32 and 32768.
+     * @defaultValue 2048
+     */
+    fftSize?: number;
+    /**
+     * Smoothing constant for the analyser node.
+     * @defaultValue 0.8
+     */
+    smoothingTimeConstant?: number;
+    /**
+     * If `true`, uses float frequency data; otherwise uses byte frequency data.
+     * @defaultValue false
+     */
+    useFloat?: boolean;
+}
+/** Whether we are running in a web (browser/Electron) environment as opposed to Node/React Native. */
+export declare function isWeb(): boolean;
+/** Whether the current device is a mobile device. */
+export declare function isMobile(): boolean;
+export declare function isFireFox(): boolean;
+export declare function isSafari(): boolean;
+export declare function isSafariBased(): boolean;
+export declare function isChromiumBased(): boolean;
+/** Check whether the current browser supports the minimum WebRTC features. */
+export declare function isBrowserSupported(): boolean;
+/** Whether the browser supports adaptive stream (IntersectionObserver + ResizeObserver). */
+export declare function supportsAdaptiveStream(): boolean;
+/** Whether the browser is likely to support dynacast (simulcast encoding control). */
+export declare function supportsDynacast(): boolean;
+/**
+ * Check for AV1 support. Safari reports AV1 capability on iPhone 14 but
+ * doesn't actually support it; Firefox supports AV1 decode but SVC
+ * publishing is broken.
+ */
+export declare function supportsAV1(): boolean;
+/**
+ * Check for VP9 support. Firefox VP9 SVC publishing is broken
+ * (https://bugzilla.mozilla.org/show_bug.cgi?id=1633876). Safari below
+ * version 16 does not support VP9.
+ */
+export declare function supportsVP9(): boolean;
+/** Check for H.265/HEVC support via `RTCRtpSender.getCapabilities`. */
+export declare function supportsH265(): boolean;
+/** Whether the browser supports `HTMLMediaElement.setSinkId` for audio output device selection. */
+export declare function supportsAudioOutputSelection(): boolean;
+/**
+ * Compare two version strings (e.g. "17.4.1" vs "17.2").
+ * Returns negative if a < b, 0 if equal, positive if a > b.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/** Detect the current browser name, version, and OS. */
+export declare function getBrowser(): BrowserDetails;
+/**
+ * Create a silent audio `MediaStreamTrack`. Useful as a placeholder when
+ * a real track isn't available.
+ */
+export declare function getEmptyAudioStreamTrack(): MediaStreamTrack;
+/**
+ * Create a black video `MediaStreamTrack`. Useful as a placeholder when
+ * a real track isn't available.
+ */
+export declare function getEmptyVideoStreamTrack(width?: number, height?: number): MediaStreamTrack;
+/**
+ * Attempt to determine facing mode from a device label string.
+ * Returns `'user'` for front cameras and `'environment'` for back cameras.
+ */
+export declare function facingModeFromDeviceLabel(label: string): string | undefined;
+/**
+ * Detect facing mode from an existing {@link LocalTrack} by inspecting
+ * track settings and device label.
+ */
+export declare function facingModeFromLocalTrack(track: LocalTrack): string | undefined;
+/**
+ * Create a Web Audio `AnalyserNode` connected to a track's audio.
+ * Returns the analyser and a cleanup function.
+ */
+export declare function createAudioAnalyser(track: Track, options?: AudioAnalyserOptions): {
+    analyser: AnalyserNode;
+    cleanup: () => void;
+};
+/** Safari 17+ or iOS 17+. */
+export declare function isSafari17Based(): boolean;
+/**
+ * Safari 18.4+ uses a different SVC API that requires
+ * `scaleResolutionDownBy` to be set on each encoding.
+ */
+export declare function isSafariSvcApi(browser?: BrowserDetails): boolean;
+/**
+ * Unwrap a `ConstrainDOMString` / `ConstrainULong` / `ConstrainDouble` to
+ * its primitive value. Handles plain values, `{ exact }`, `{ ideal }`, and
+ * arrays (returns the first element).
+ */
+export declare function unwrapConstraint(constraint: ConstrainDOMString): string;
+export declare function unwrapConstraint(constraint: ConstrainULong): number;
+export declare function unwrapConstraint(constraint: ConstrainDouble): number;

package/dist/utils/deviceFailure.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The type of device failure that occurred.
+ */
+export type DeviceFailureKind = 'PermissionDenied' | 'NotFound' | 'DeviceInUse';
+/**
+ * Utility class for determining the type of media device failure from an error
+ * object.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await createLocalAudioTrack();
+ * } catch (e) {
+ *   const failure = MediaDeviceFailure.getFailure(e);
+ *   if (failure === 'PermissionDenied') {
+ *     // show permission dialog
+ *   }
+ * }
+ * ```
+ */
+export declare class MediaDeviceFailure {
+    /**
+     * Determine the failure kind from a caught error.
+     *
+     * @param error - The error thrown by `getUserMedia` or similar APIs.
+     * @returns The categorised failure, or `undefined` if the error is not a
+     *   recognised device failure.
+     */
+    static getFailure(error: any): DeviceFailureKind | undefined;
+}

package/dist/utils/id.d.ts

@@ -0,0 +1 @@
+export declare function generateLogId(): string;

package/dist/utils/logger.d.ts

@@ -0,0 +1,39 @@
+export declare enum LogLevel {
+    TRACE = 0,
+    DEBUG = 1,
+    INFO = 2,
+    WARN = 3,
+    ERROR = 4,
+    SILENT = 5
+}
+export interface LoggerInterface {
+    trace(msg: string, ...args: any[]): void;
+    debug(msg: string, ...args: any[]): void;
+    info(msg: string, ...args: any[]): void;
+    warn(msg: string, ...args: any[]): void;
+    error(msg: string, ...args: any[]): void;
+}
+/**
+ * Callback signature for log extensions. Receives the log level, formatted
+ * message, and any additional context passed to the logger call.
+ */
+export type LogExtension = (level: LogLevel, msg: string, context: Record<string, unknown>) => void;
+export declare function setLogLevel(level: LogLevel): void;
+export declare function getLogLevel(): LogLevel;
+export declare function setLogger(logger: LoggerInterface): void;
+/**
+ * Set an extension handler that receives all SDK log messages. This can be
+ * used to forward logs to a third-party logging service (e.g. Sentry,
+ * Datadog).
+ *
+ * @param handler - The extension handler function, or `undefined` to remove.
+ *
+ * @example
+ * ```ts
+ * setLogExtension((level, msg, context) => {
+ *   myLoggingService.log({ level: LogLevel[level], message: msg, ...context });
+ * });
+ * ```
+ */
+export declare function setLogExtension(handler: LogExtension | undefined): void;
+export declare function getLogger(tag: string): LoggerInterface;

package/dist/utils/typedEmitter.d.ts

@@ -0,0 +1,24 @@
+import { EventEmitter } from 'events';
+/**
+ * A typed wrapper over Node's `EventEmitter`.
+ *
+ * Extends `EventEmitter` with `declare` overrides so that `emit`, `on`,
+ * `off`, etc. are type-safe without introducing circular-reference issues
+ * that arise when using `typed-emitter` directly in `extends` clauses
+ * whose event maps reference the class itself.
+ *
+ * Runtime behaviour is 100% `EventEmitter`; this class adds zero runtime
+ * code.
+ */
+export declare class TypedEmitter<T extends Record<string, (...args: any[]) => void> = {}> extends EventEmitter {
+    emit: <E extends string | number>(event: E, ...args: E extends keyof T ? Parameters<T[E]> : any[]) => boolean;
+    on: <E extends string | number>(event: E, listener: E extends keyof T ? T[E] : (...args: any[]) => void) => this;
+    once: <E extends string | number>(event: E, listener: E extends keyof T ? T[E] : (...args: any[]) => void) => this;
+    off: <E extends string | number>(event: E, listener: E extends keyof T ? T[E] : (...args: any[]) => void) => this;
+    addListener: <E extends string | number>(event: E, listener: E extends keyof T ? T[E] : (...args: any[]) => void) => this;
+    removeListener: <E extends string | number>(event: E, listener: E extends keyof T ? T[E] : (...args: any[]) => void) => this;
+    removeAllListeners: (event?: string | number) => this;
+    listeners: <E extends string | number>(event: E) => E extends keyof T ? T[E][] : ((...args: any[]) => void)[];
+    rawListeners: <E extends string | number>(event: E) => E extends keyof T ? T[E][] : ((...args: any[]) => void)[];
+    listenerCount: (event: string | number) => number;
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.1.0";
+export declare const PROTOCOL_VERSION = 1;

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@axonkit/client-sdk-js",
+  "version": "0.1.0",
+  "description": "AxonKit JS/TS Client SDK based on mediasoup-client",
+  "main": "dist/axonkit-client.umd.js",
+  "module": "dist/axonkit-client.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "build:clean": "rm -rf dist && rollup -c",
+    "docs": "typedoc",
+    "lint": "eslint src/",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "vitest run src",
+    "dev": "vite examples/demo",
+    "size": "size-limit",
+    "clean": "rm -rf dist docs",
+    "verify:dist": "test -f dist/axonkit-client.esm.js && test -f dist/axonkit-client.umd.js && test -f dist/index.d.ts && ! ls dist/**/*.map 2>/dev/null | grep -q . && echo 'dist OK (no source maps shipped)'",
+    "prepublishOnly": "npm run clean && npm run build && npm run verify:dist"
+  },
+  "keywords": [
+    "webrtc",
+    "mediasoup",
+    "axonkit",
+    "realtime"
+  ],
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "axonkit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/axonkit/client-sdk-js.git"
+  },
+  "homepage": "https://github.com/axonkit/client-sdk-js#readme",
+  "bugs": {
+    "url": "https://github.com/axonkit/client-sdk-js/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "async-mutex": "^0.5.0",
+    "events": "^3.3.0",
+    "mediasoup-client": "^3.18.7",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^29.0.1",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@size-limit/preset-small-lib": "^12.0.1",
+    "@types/events": "^3.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "eslint": "^10.0.2",
+    "eslint-config-prettier": "^10.1.0",
+    "eslint-plugin-prettier": "^5.2.0",
+    "happy-dom": "^17.4.4",
+    "prettier": "^3.8.1",
+    "rollup": "^4.59.0",
+    "size-limit": "^12.0.1",
+    "typedoc": "^0.28.17",
+    "typescript": "^5.9.3",
+    "vite": "^6.3.0",
+    "vitest": "^3.1.0"
+  },
+  "packageManager": "pnpm@10.22.0"
+}