@ikonai/sdk 1.0.43 → 1.0.45

package/channel/channel-manager.d.ts

@@ -33,6 +33,12 @@ export interface ChannelManagerConfig {
      * Useful for worker environments where localStorage might be unavailable.
      */
     orderedEndpointTypes?: EntrypointType[];
+    /**
+     * True when the user has explicitly constrained the allowed transports via
+     * `proxy`, `websocket`, or `webtransport` settings. When set, unstable types
+     * are not demoted on reconnect — the user's transport choice is respected.
+     */
+    hasTransportConstraint?: boolean;
     /**
      * Called when a working endpoint type is discovered.
      * Typically used by the host to persist endpoint preference.
@@ -55,6 +61,15 @@ export interface ChannelManagerConfig {
      * WebRTC-type entrypoints are filtered out (they are signal-only, not real channels).
      */
     webRtcEnabled?: boolean;
+    /**
+     * Called during transport fallback when a partial connection occurred.
+     * Returns fresh entrypoints from a new /connect call so the next transport
+     * type uses a clean server session with no stale channel state.
+     */
+    onRefreshEntrypoints?: () => Promise<{
+        entrypoints: Entrypoint[];
+        sessionId: number;
+    }>;
 }
 /**
  * ChannelManager orchestrates multiple channels to an Ikon server.

package/client/endpoint-selector.d.ts

@@ -29,6 +29,13 @@ export declare class EndpointSelector {
     });
     get proxyMode(): ProxyMode;
     get proxyPreferred(): boolean;
+    /**
+     * True when the user has explicitly narrowed the set of allowed transports
+     * via `proxy`, `websocket`, or `webtransport` settings. In that case the SDK
+     * should respect the user's choice rather than silently reordering types
+     * (e.g. demoting an "unstable" type on transient failure).
+     */
+    get hasTransportConstraint(): boolean;
     /**
      * Mark proxy as preferred and persist to localStorage.
      * Called by IkonClient when auth-level proxy fallback succeeds in auto mode.

package/client/ikon-client-config.d.ts

@@ -177,7 +177,7 @@ export interface TimeoutConfig {
     slowConnectionThresholdMs?: number;
     /**
      * Duration in milliseconds before giving up and showing offline.
-     * Default: 60000 (60 seconds)
+     * Default: 180000 (3 minutes)
      */
     connectionTimeoutMs?: number;
     /**
@@ -252,6 +252,8 @@ export interface VideoConfig {
 export interface WebRtcConfig {
     /** Enable WebRTC for audio and video. Default: true */
     enabled?: boolean;
+    /** ICE servers (TURN/STUN) for WebRTC. Server-provided ICE servers take precedence. */
+    iceServers?: RTCIceServer[];
 }
 /**
  * Configuration for IkonClient.
@@ -349,7 +351,7 @@ export interface IkonClientConfig {
     proxy?: boolean;
 }
 export declare const DEFAULT_SLOW_CONNECTION_THRESHOLD_MS = 5000;
-export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 60000;
+export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 180000;
 export declare const DEFAULT_KEEPALIVE_TIMEOUT_MS = 15000;
 export declare const DEFAULT_RECONNECT_BACKOFF_MS = 2000;
 export declare const DEFAULT_MAX_RECONNECT_ATTEMPTS = 2;

package/client/ikon-client.d.ts

@@ -90,8 +90,10 @@ export type StateHandler = (state: ConnectionState) => void;
 export declare class IkonClient {
     private channelManager;
     private protocolWorker;
+    private preloadedWorker;
     private workerManagerState;
     private authResponse;
+    private _connectUrl;
     private currentState;
     private slowConnectionTimer;
     private connectionTimer;
@@ -119,6 +121,7 @@ export declare class IkonClient {
     private unregisterBrowserFunctions;
     private unregisterMediaCaptureFunctions;
     private unregisterSoundFunctions;
+    private unregisterLoginInterceptor;
     private nextProtocolPortId;
     private nextProtocolSendPortId;
     private readonly _audioEnabled;
@@ -130,6 +133,7 @@ export declare class IkonClient {
     private _webRtcAudioStreams;
     private _webRtcVideoStreams;
     private _webRtcTrackMap;
+    private _pendingActiveAudioTracks;
     private _keepaliveLockAbort;
     private _fullReauthAttempted;
     private _softReconnectAttempted;
@@ -310,10 +314,9 @@ export declare class IkonClient {
     private setupWebRtcSignaling;
     private _webRtcAudioUnlockHandler;
     private readonly _webRtcMediaSession;
-    private ensureWebRtcAudioElement;
-    private playWebRtcAudioTrack;
+    private createWebRtcAudioElement;
+    private destroyWebRtcAudioElement;
     private ensureWebRtcAudioUnlockHandler;
-    private stopWebRtcAudioTrack;
     private setupWebRtcMediaSession;
     private removeWebRtcAudioUnlockHandler;
     private connectProtocolOnMainThread;

package/connection/urls.d.ts

@@ -15,6 +15,7 @@ export declare const IKON_AUTH_URL_DEV = "https://auth.dev.ikonai.com";
 export declare const IKON_AUTH_BASE_URL = "https://auth.ikonai.com";
 /**
  * Get backend URL from BackendType.
+ * Honors ?ikon-api=true by routing through the same-origin /ikon/api path.
  */
 export declare function getBackendUrl(backendType?: BackendType): string;
 /**
@@ -22,9 +23,10 @@ export declare function getBackendUrl(backendType?: BackendType): string;
  * Priority:
  * 1. Explicit override (e.g. from config)
  * 2. VITE_IKON_BACKEND_URL env var (set by .NET server during local dev)
- * 3. Local environment (localhost, LAN IPs) → IKON_BACKEND_URL_DEV
- * 4. Hostname contains '.dev.' → IKON_BACKEND_URL_DEV
- * 5. Default → IKON_BACKEND_URL_PROD
+ * 3. ikon-api=true query param → same-origin /ikon/api
+ * 4. Local environment (localhost, LAN IPs) → IKON_BACKEND_URL_DEV
+ * 5. Hostname contains '.dev.' → IKON_BACKEND_URL_DEV
+ * 6. Default → IKON_BACKEND_URL_PROD
  */
 export declare function deriveBackendUrl(override?: string): string;
 /**

package/functions/function-registry.d.ts

@@ -1,5 +1,5 @@
 import { ProtocolMessage, ActionFunctionRegister, GlobalState } from '../../../../shared/protocol/src/index.ts';
-import { FunctionDefinition, FunctionHandler, NormalizedFunction } from './types';
+import { FunctionCallError, FunctionDefinition, FunctionHandler, NormalizedFunction } from './types';
 export interface RemoteFunction {
     id: string;
     name: string;
@@ -11,6 +11,15 @@ export interface RemoteFunction {
     llmCallOnlyOnce: boolean;
     requiresInstance: boolean;
 }
+/**
+ * An error interceptor can observe and optionally handle function call errors.
+ * Return a Promise to take over resolution of the original call (e.g. retry after login).
+ * Return null to let the error propagate normally.
+ */
+export type ErrorInterceptor = (error: FunctionCallError, callInfo: {
+    functionName: string;
+    args: unknown[];
+}) => Promise<unknown> | null;
 export interface FunctionRegistryConfig {
     sendProtocolMessage: (message: ProtocolMessage) => void;
     sessionId: number;
@@ -19,6 +28,7 @@ export declare class FunctionRegistry {
     private readonly functions;
     private readonly remoteFunctions;
     private readonly pendingCalls;
+    private readonly errorInterceptors;
     private config;
     private isConnected;
     /**
@@ -30,6 +40,11 @@ export declare class FunctionRegistry {
      * Detach from the client (on disconnect).
      */
     detach(): void;
+    /**
+     * Add an error interceptor that can handle or transform function call errors.
+     * Returns an unregister function.
+     */
+    addErrorInterceptor(interceptor: ErrorInterceptor): () => void;
     /**
      * Register a function with the registry.
      * If already connected, sends registration to server immediately.

package/functions/index.d.ts

@@ -1,5 +1,5 @@
 export type { ValueDescriptor, NormalizedValueDescriptor, PrimitiveValueKind, FunctionParameterDefinition, FunctionDefinition, FunctionHandler, FunctionResultWithData } from './types';
 export { withResultData, FunctionCallError } from './types';
-export { FunctionRegistry, type FunctionRegistryConfig } from './function-registry';
+export { FunctionRegistry, type FunctionRegistryConfig, type ErrorInterceptor } from './function-registry';
 export { registerBrowserFunctions, isBrowserEnvironment } from './browser-functions';
 export { registerSoundFunctions, SoundFunctionNames } from './sound-functions';

package/functions/types.d.ts

@@ -67,6 +67,7 @@ export interface NormalizedFunction {
 export declare class FunctionCallError extends Error {
     readonly remoteErrorType: string;
     readonly remoteStackTrace: string;
-    constructor(message: string, remoteErrorType: string, remoteStackTrace: string);
+    readonly code: string;
+    constructor(message: string, remoteErrorType: string, remoteStackTrace: string, code?: string);
 }
 export {};

package/index.d.ts

@@ -14,17 +14,19 @@ export { setLogLevel, setLogSink, getLogLevel, getLogSink, createLogger, LogLeve
 export type { LogEntry, LogSink, Logger, LogEventListener, LogEventSubscriptionOptions } from './utils/logger';
 export { initializeDebugMode, isDebugModeEnabled } from './utils/debug-mode';
 export { initializeInspectMode, isInspectModeEnabled, enableInspectMode } from './utils/inspect-mode';
-export { getLangParam, getProxyParam, getWebSocketParam, getWebTransportParam, getDebugParam, getServerUrlParam, getAudioParam, getVideoParam, getWebRtcParam, getInspectParam, setSdkUrlParam, IKON_PARAM_PROXY, IKON_PARAM_WEBSOCKET, IKON_PARAM_WEBTRANSPORT, IKON_PARAM_DEBUG, IKON_PARAM_LANG, IKON_PARAM_SERVER_URL, IKON_PARAM_GIT_SOURCE, IKON_PARAM_GIT_BRANCH, IKON_PARAM_AUDIO, IKON_PARAM_VIDEO, IKON_PARAM_WEBRTC, IKON_PARAM_INSPECT } from './utils/query-params';
+export { getLangParam, getProxyParam, getWebSocketParam, getWebTransportParam, getDebugParam, getServerUrlParam, getAudioParam, getVideoParam, getWebRtcParam, getInspectParam, getRetryParam, setSdkUrlParam, IKON_PARAM_PROXY, IKON_PARAM_WEBSOCKET, IKON_PARAM_WEBTRANSPORT, IKON_PARAM_DEBUG, IKON_PARAM_LANG, IKON_PARAM_SERVER_URL, IKON_PARAM_GIT_SOURCE, IKON_PARAM_GIT_BRANCH, IKON_PARAM_AUDIO, IKON_PARAM_VIDEO, IKON_PARAM_WEBRTC, IKON_PARAM_INSPECT, IKON_PARAM_RETRY } from './utils/query-params';
 export { getOpcodeName } from './utils/opcode-names';
 export { initializeLogSink, setSendLogsCallback, getBufferedLogs, takeBufferedLogs, flushLogs, clearLogBuffer, getLogBufferSize } from './utils/log-sink';
 export type { LogSinkConfig } from './utils/log-sink';
 export { startLogSender, stopLogSender } from './utils/log-sender';
-export { FunctionRegistry, registerBrowserFunctions, isBrowserEnvironment, FunctionCallError, type FunctionRegistryConfig } from './functions';
+export { FunctionRegistry, registerBrowserFunctions, isBrowserEnvironment, FunctionCallError, type FunctionRegistryConfig, type ErrorInterceptor } from './functions';
 export { withResultData } from './functions';
 export type { ValueDescriptor, NormalizedValueDescriptor, PrimitiveValueKind, FunctionParameterDefinition, FunctionDefinition, FunctionHandler, FunctionResultWithData } from './functions';
+export { loginErrorInterceptor, reprovisionAfterLogin, consumeLoginHandoff, getLoginPromptState, clearLoginPrompt, subscribe as subscribeLoginPrompt, consumeLoginPendingCall } from './login';
+export type { LoginPromptState, LoginPendingCall } from './login';
 export { IKON_AUTH_BASE_URL, IKON_AUTH_URL_PROD, IKON_AUTH_URL_DEV, IKON_BACKEND_URL_PROD, IKON_BACKEND_URL_DEV, deriveAuthUrl, deriveBackendUrl, deriveBackendType, parseUrlParams, clearSessionParamsFromUrl, isCloudEnvironment, type UrlParams } from './connection/urls';
 export { getOrCreateDeviceId, clearDeviceId, extractUserIdFromToken } from './storage';
 export { IkonMedia, IkonAudioPlayback, IkonVideoPlayback, isSharedArrayBufferSupported, isAudioWorkletSupported, IkonMediaCapture, IkonVideoCapture, IkonAudioCapture, IkonImageCapture } from './media';
 export type { IkonMediaConfig, IkonAudioPlaybackConfig, IkonVideoPlaybackConfig, IkonVideoCaptureHandle, IkonVideoCaptureRequest, IkonVideoCaptureOptions, VideoCaptureSource, IkonAudioCaptureHandle, IkonAudioCaptureRequest, IkonAudioCaptureOptions, IkonImageCaptureRequest, IkonImageCaptureResult } from './media';
-export { WebRTCConnection, WebRTCSignaling, WEBRTC_AUDIO_CODEC, WEBRTC_AUDIO_SAMPLE_RATE, WEBRTC_AUDIO_CHANNELS, WEBRTC_AUDIO_BITRATE, WEBRTC_AUDIO_JITTER_BUFFER_TARGET_MS, WEBRTC_VIDEO_CODEC, WEBRTC_VIDEO_MAX_BITRATE, WEBRTC_VIDEO_MAX_FRAMERATE, WEBRTC_BUNDLE_POLICY, WEBRTC_RTCP_MUX_POLICY, WEBRTC_ICE_SERVERS, WEBRTC_DATA_CHANNEL_LABEL, WEBRTC_DATA_CHANNEL_ORDERED, WEBRTC_DATA_CHANNEL_MAX_RETRANSMITS, WEBRTC_MAX_AUDIO_TRACKS, WEBRTC_MAX_VIDEO_TRACKS } from './webrtc';
+export { WebRTCConnection, WebRTCSignaling, WEBRTC_AUDIO_CODEC, WEBRTC_AUDIO_SAMPLE_RATE, WEBRTC_AUDIO_CHANNELS, WEBRTC_AUDIO_BITRATE, WEBRTC_AUDIO_JITTER_BUFFER_TARGET_MS, WEBRTC_VIDEO_CODEC, WEBRTC_VIDEO_MAX_BITRATE, WEBRTC_VIDEO_MAX_FRAMERATE, WEBRTC_BUNDLE_POLICY, WEBRTC_RTCP_MUX_POLICY, WEBRTC_DATA_CHANNEL_LABEL, WEBRTC_DATA_CHANNEL_ORDERED, WEBRTC_DATA_CHANNEL_MAX_RETRANSMITS, WEBRTC_MAX_AUDIO_TRACKS, WEBRTC_MAX_VIDEO_TRACKS } from './webrtc';
 export type { WebRTCConnectionConfig, WebRTCConnectionState, WebRTCSignalingConfig } from './webrtc';