@ikonai/sdk 1.0.44 → 1.0.46

package/channel/channel-manager.d.ts

@@ -55,6 +55,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.
@@ -75,8 +84,6 @@ export declare class ChannelManager {
     private shouldReconnect;
     private entrypoints;
     private abortController;
-    private demotedTypes;
-    private connectionStable;
     private connectionTimeoutMs;
     private readonly config;
     constructor(config: ChannelManagerConfig);
@@ -114,6 +121,13 @@ export declare class ChannelManager {
      * stopping) clear the channels and transition to idle/stopped before this runs.
      */
     checkHealth(): void;
+    /**
+     * Force every active channel to drop its transport and notify the manager,
+     * kicking off the normal reconnect flow. Used when a higher layer has
+     * evidence that the connection is dead (e.g. no ACK received for a user
+     * action within the ack-timeout window).
+     */
+    triggerReconnect(reason: string): void;
     /**
      * Internal connect implementation.
      * @param isReconnect - If true, don't set offline state on failure (let attemptReconnect handle it)
@@ -137,6 +151,11 @@ export declare class ChannelManager {
     private handleChannelStateChange;
     /**
      * Handle channel close.
+     *
+     * Only `CORE_ON_SERVER_STOPPING` (handled separately via channel state →
+     * `handleChannelStateChange`) means the server is gone. Any transport-level
+     * close — including a clean WebSocket code 1000 — just means this transport
+     * dropped, and we reconnect.
      */
     private handleChannelClose;
     /**

package/channel/channel.d.ts

@@ -36,9 +36,8 @@ export interface ChannelConfig {
      * Callback when channel is closed.
      * @param reason - Optional reason for the close
      * @param wasClean - Whether the close was clean (normal)
-     * @param isServerClose - Whether the close code was 1000 or 1001, indicating server-initiated close
      */
-    onClose?: (reason?: string, wasClean?: boolean, isServerClose?: boolean) => void;
+    onClose?: (reason?: string, wasClean?: boolean) => void;
     /**
      * Callback when an error occurs.
      */
@@ -83,6 +82,13 @@ export declare class Channel {
      * Disconnect the channel.
      */
     disconnect(): void;
+    /**
+     * Force the channel to drop its transport and notify the manager so the
+     * normal reconnect flow kicks in. Used when an upper layer (e.g. action-ack
+     * timeout) has evidence the connection is dead even though the transport
+     * still believes it is open.
+     */
+    triggerReconnect(reason: string): void;
     /**
      * Check transport health and trigger close if the connection is dead.
      * Used after tab resume to detect WebSockets closed by the OS while suspended.

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;
     /**
@@ -197,6 +197,14 @@ export interface TimeoutConfig {
      * Default: 2
      */
     maxReconnectAttempts?: number;
+    /**
+     * Timeout in ms for server ACK of a user action call.
+     * If the server does not acknowledge an action call within this window, the SDK
+     * assumes the connection is dead and triggers reconnection. Kept well under
+     * keepaliveTimeoutMs so we detect network-down faster than the keepalive watchdog.
+     * Default: 5000 (5 seconds)
+     */
+    actionAckTimeoutMs?: number;
 }
 /**
  * Media Session metadata for OS-level media controls (lock screen, notifications).
@@ -338,9 +346,15 @@ export interface IkonClientConfig {
      */
     websocket?: boolean;
     /**
-     * Force WebTransport transport only. When true, only WebTransport (and WebTransportProxy)
-     * endpoint types are used. When false, WebTransport types are excluded.
-     * Can be overridden by the `?ikon-webtransport=` query parameter.
+     * Enable WebTransport.
+     *
+     * WebTransport is disabled by default because it has proven unreliable on bad
+     * networks. Apps opt in by setting this to `true`, which makes the SDK include
+     * WebTransport (and WebTransportProxy) endpoint types and prefer them over
+     * WebSocket. When left unset or set to `false`, WebTransport types are excluded
+     * and the SDK uses WebSocket / WebSocketProxy only.
+     *
+     * Can be overridden by the `?ikon-webtransport=true|false` query parameter.
      */
     webtransport?: boolean;
     /**
@@ -351,10 +365,11 @@ 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;
+export declare const DEFAULT_ACTION_ACK_TIMEOUT_MS = 5000;
 export declare const DEFAULT_PROVISIONING_TIMEOUT_MS = 60000;
 export declare const OFFLINE_SOFT_RETRY_THRESHOLD_MS: number;
 export declare const RECONNECT_RETRY_INTERVAL_MS: number;

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;
@@ -104,12 +106,15 @@ export declare class IkonClient {
     private readonly config;
     private readonly slowConnectionThresholdMs;
     private readonly connectionTimeoutMs;
+    private readonly actionAckTimeoutMs;
+    private readonly _pendingActionAcks;
     private readonly endpointSelector;
     private boundBeforeUnload;
     private boundPageHide;
     private boundVisibilityChange;
     private boundPopstate;
     private boundOnline;
+    private boundOffline;
     private _globalState;
     private _globalStateReceived;
     private _channelsConnected;
@@ -119,6 +124,7 @@ export declare class IkonClient {
     private unregisterBrowserFunctions;
     private unregisterMediaCaptureFunctions;
     private unregisterSoundFunctions;
+    private unregisterLoginInterceptor;
     private nextProtocolPortId;
     private nextProtocolSendPortId;
     private readonly _audioEnabled;
@@ -130,6 +136,7 @@ export declare class IkonClient {
     private _webRtcAudioStreams;
     private _webRtcVideoStreams;
     private _webRtcTrackMap;
+    private _pendingActiveAudioTracks;
     private _keepaliveLockAbort;
     private _fullReauthAttempted;
     private _softReconnectAttempted;
@@ -137,6 +144,7 @@ export declare class IkonClient {
     private _disconnectedAt;
     private _reconnectTimer;
     private _serverStopped;
+    private _hasBeenConnected;
     private _waitForExternalConnectUrl;
     private _externalConnectUrlCleanup;
     /**
@@ -179,7 +187,9 @@ export declare class IkonClient {
     onWebRtcTrackMapChanged?: (info: WebRTCTrackMapInfo) => void;
     /**
      * Look up the WebRTC video MediaStream for a given app-level stream ID.
-     * Returns null if no track is mapped to this stream ID or if the stream is inactive.
+     * Checks remote tracks first, then falls back to local capture streams so single-user
+     * self-preview works (e.g. a security-camera app showing its own webcam).
+     * Returns null if no match or if the stream is inactive.
      */
     getWebRtcVideoStreamByStreamId(streamId: string): MediaStream | null;
     /**
@@ -227,6 +237,14 @@ export declare class IkonClient {
      */
     disconnect(): void;
     sendActionCall(actionId: string, payload?: string): void;
+    /**
+     * Register an outstanding action call and start its ack-timeout timer. If the
+     * server does not echo back an ActionCallAck for this CallId within
+     * `actionAckTimeoutMs`, we assume the connection is dead and force reconnect.
+     */
+    private trackPendingActionAck;
+    private onActionAckTimeout;
+    private clearPendingActionAcks;
     /**
      * Send a protocol message to the server.
      * Routes to appropriate channel based on the message's opcode group.
@@ -299,6 +317,13 @@ export declare class IkonClient {
     private handleChannelManagerStateChange;
     /**
      * Update the connection state and notify subscribers.
+     *
+     * Principle: once connected, the only allowed path to 'offline' is an
+     * explicit `CORE_ON_SERVER_STOPPING` from the server, which sets
+     * `_serverStopped = true` first. Any other attempt is a bug — redirect to
+     * the infinite reconnect loop and log so we notice in dev. Exception: when
+     * retry is disabled via ikon-retry=false the caller has opted out of
+     * reconnection, so let the offline transition through.
      */
     private setState;
     /**
@@ -310,10 +335,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;
@@ -335,6 +359,7 @@ export declare class IkonClient {
     private scheduleReconnectRetry;
     private clearReconnectTimer;
     private attemptReconnectOnVisible;
+    private handleBrowserOffline;
     /**
      * Clear all timers.
      */

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.
+ * Defaults to same-origin /ikon/api on deployed apps; honors ?ikon-api=false to opt out.
  */
 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. Cloud environment, not opted out via ?ikon-api=false → same-origin /ikon/api (default)
+ * 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,14 +14,16 @@ 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';