@ikonai/sdk 1.7.0 → 1.10.0

package/channel/channel-manager.d.ts

@@ -156,6 +156,7 @@ export declare class ChannelManager {
     /**
      * Group entrypoints by type.
      */
+    private static isNativeOnlyType;
     private groupByType;
     /**
      * Handle channel state change.

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

@@ -394,6 +394,9 @@ export interface IkonClientConfig {
      */
     interceptInternalLinks?: boolean;
 }
+/** Where a local dev server listens when nothing says otherwise; the vite template bakes the same pair. */
+export declare const DEFAULT_LOCAL_SERVER_HOST = "localhost";
+export declare const DEFAULT_LOCAL_SERVER_PORT = 8443;
 export declare const DEFAULT_SLOW_CONNECTION_THRESHOLD_MS = 5000;
 export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 180000;
 export declare const PROTOCOL_WORKER_CONNECT_TIMEOUT_MS = 30000;

package/client/ikon-client.d.ts

@@ -62,44 +62,29 @@ export interface ProtocolMessageSubscriptionOptions {
  * State handler callback type for state subscribers.
  */
 export type StateHandler = (state: ConnectionState) => void;
+/** How a dispatched UI action should be treated when the server refuses it. */
+export interface SendActionCallOptions {
+    /**
+     * The dispatch is a component's own bookkeeping rather than something a person did, so a refusal
+     * is not worth a person's attention: a controlled overlay reports itself closed as it unmounts,
+     * and when the whole subtree is going away the server has already retired that action. Such a
+     * failure is logged at debug instead of error.
+     */
+    bestEffort?: boolean;
+}
 /** The server-side outcome of a dispatched UI action (see {@link IkonClient.sendActionCallWithResult}). */
 export interface ActionOutcome {
     success: boolean;
+    /** Empty: the server keeps the exception in its own log, so a failure carries no reason here. */
     errorMessage: string;
 }
-/**
- * IkonClient is the main entry point for connecting to an Ikon server.
- *
- * Features:
- * - Manages connection lifecycle
- * - Provides UI-friendly connection states (waitingForExternalConnectUrl, connecting, connected, reconnecting, offline)
- * - Handles timeouts for connection establishment
- * - Passes protocol messages to application via callback
- * - Multi-channel support (core, audio, video on separate connections)
- * - Smart endpoint selection (WT → WS → WTProxy → WSProxy)
- *
- * Usage:
- * ```typescript
- * const client = new IkonClient({
- *   local: { host: 'localhost', httpsPort: 8443 },
- *   onProtocolMessage: (message) => {
- *     const opcode = getOpcode(message)
- *     // Handle protocol messages
- *   },
- *   onConnectionStateChange: (state) => {
- *     // Update UI based on state
- *   }
- * })
- *
- * await client.connect()
- * ```
- */
 export declare class IkonClient {
     private channelManager;
     private protocolWorker;
     private preloadedWorker;
     private workerManagerState;
     private authResponse;
+    private _resumedSession;
     private _connectUrl;
     private _brandingRequired;
     private currentState;
@@ -128,6 +113,7 @@ export declare class IkonClient {
     private readonly _pendingActionAcks;
     private _ackRttMs;
     private readonly _actionIdByCallId;
+    private readonly _bestEffortCallIds;
     private readonly _pendingActionResults;
     private readonly endpointSelector;
     private readonly _webRtcReachability;
@@ -155,8 +141,10 @@ export declare class IkonClient {
     private unregisterBrowserFunctions;
     private unregisterMediaCaptureFunctions;
     private unregisterSoundFunctions;
+    private unregisterDownloadFunctions;
     private unregisterLoginInterceptor;
     private nextProtocolPortId;
+    private _deliveringViaDataChannel;
     private nextProtocolSendPortId;
     private readonly _audioEnabled;
     private readonly _videoEnabled;
@@ -187,6 +175,7 @@ export declare class IkonClient {
     private _reconnectTimer;
     private _joinWatchdogTimer;
     private _serverStopped;
+    private _credentialRejected;
     private _hasBeenConnected;
     private _waitForExternalConnectUrl;
     private _externalConnectUrlCleanup;
@@ -309,6 +298,12 @@ export declare class IkonClient {
      * Returns undefined if not connected.
      */
     get sessionId(): number | undefined;
+    /**
+     * True when this client joined a session another connection opened (a `window.__IKON_RESUME__`
+     * hand-off) rather than authenticating one of its own. Such a client starts with no UI tree: the stream
+     * began before it arrived, so it has to ask the app for a full snapshot.
+     */
+    get resumedSession(): boolean;
     /**
      * The Ikon server instance serving this connection. Stable across soft reconnects (cached
      * entrypoints, same instance); changes when a full re-authentication lands on a different
@@ -423,7 +418,7 @@ export declare class IkonClient {
      * Disconnect from the server.
      */
     disconnect(): void;
-    sendActionCall(actionId: string, payload?: string): void;
+    sendActionCall(actionId: string, payload?: string, options?: SendActionCallOptions): void;
     /**
      * Dispatch a UI action and resolve with the server handler's actual outcome — the
      * ActionResult the server emits when the handler finishes (the ActionCallAck is only a
@@ -466,6 +461,14 @@ export declare class IkonClient {
      * Routes to appropriate channel based on the message's opcode group.
      */
     sendProtocolMessage(message: ProtocolMessage): void;
+    /**
+     * Hand an error to the app's onError callback.
+     *
+     * For SDK subsystems (media playback, capture) whose failure leaves the connection itself
+     * intact: the client stays connected, so this callback is the only place the app can learn
+     * that a session went silent or blind.
+     */
+    reportError(error: Error): void;
     /**
      * Send a client context update to the server.
      * This notifies the server of changes to viewport size, theme, or timezone.
@@ -562,6 +565,10 @@ export declare class IkonClient {
      */
     private setErrorState;
     private connectProtocol;
+    /** Media setup that must follow EVERY successful protocol connect. It used to live only on the
+     * worker path's tail, so the two no-Worker fallbacks connected without audio, video or WebRTC —
+     * a silent client on exactly the browsers that already lack workers. */
+    private finishMediaSetup;
     private ensureVisemeTracker;
     /**
      * Builds and enables the custom (non-WebRTC) playback pipeline. This is the
@@ -612,6 +619,7 @@ export declare class IkonClient {
     private connectProtocolOnMainThread;
     private disconnectProtocol;
     private getServerKeepaliveTimeoutMs;
+    private getSoftRetryWindowMs;
     private groupEntrypointsByType;
     /**
      * Tell the developer — and through them, whoever runs the network — that this session is on the
@@ -677,6 +685,7 @@ export declare class IkonClient {
     private requestExternalConnectUrl;
     private attemptReconnectOnVisible;
     private handleBrowserOffline;
+    private forceReconnectAfterOffline;
     /**
      * Clear all timers.
      */

package/functions/download-functions.d.ts

@@ -0,0 +1,8 @@
+import { FunctionRegistry } from './function-registry';
+export declare const DownloadFunctionNames: {
+    readonly DownloadFile: "ikon.client.downloadFile";
+};
+/**
+ * Register download functions with a registry. Returns an unregister function.
+ */
+export declare function registerDownloadFunctions(registry: FunctionRegistry): () => void;

package/functions/index.d.ts

@@ -3,3 +3,4 @@ export { withResultData, FunctionCallError } from './types';
 export { FunctionRegistry, type FunctionRegistryConfig, type ErrorInterceptor } from './function-registry';
 export { registerBrowserFunctions, isBrowserEnvironment } from './browser-functions';
 export { registerSoundFunctions, SoundFunctionNames } from './sound-functions';
+export { registerDownloadFunctions, DownloadFunctionNames } from './download-functions';

package/index.d.ts

@@ -1,6 +1,7 @@
-export { IkonClient, type ActionOutcome, type ProtocolMessageHandler, type StateHandler, type ProtocolMessageSubscriptionOptions, type ProtocolMessagePort, type ProtocolSendPort, type WebRTCTrackMapInfo } from './client/ikon-client';
+export { IkonClient, type ActionOutcome, type SendActionCallOptions, type ProtocolMessageHandler, type StateHandler, type ProtocolMessageSubscriptionOptions, type ProtocolMessagePort, type ProtocolSendPort, type WebRTCTrackMapInfo } from './client/ikon-client';
 export { AppMessaging, appMessaging, type AppMessageType, type AppMessageSubscription } from './app-messaging';
 export type { IkonClientConfig, LocalConfig, ApiKeyConfig, SessionTokenConfig, CloudConnectionConfig, CommonConnectionConfig, TimeoutConfig, BackendType, AudioConfig, VideoConfig, MediaSessionConfig, WebRtcConfig } from './client/ikon-client-config';
+export { DEFAULT_LOCAL_SERVER_HOST, DEFAULT_LOCAL_SERVER_PORT, DEFAULT_SLOW_CONNECTION_THRESHOLD_MS } from './client/ikon-client-config';
 export type { ConnectionState } from './client/connection-state';
 export { isConnecting, isConnected, isOffline, isError } from './client/connection-state';
 export { ChannelManager, type ChannelManagerConfig, type ChannelManagerState } from './channel/channel-manager';
@@ -20,7 +21,7 @@ export { abortSignalTimeout, abortSignalAny } from './utils/abort-signal';
 export { createPkceChallenge, takePkceVerifier, restorePkceVerifier, isPkceSupported } from './utils/pkce';
 export { isEmbedded, startEmbeddedOAuthSignIn, adoptPkceVerifierFromUrl, onEmbeddedOAuthResult, type EmbeddedOAuthResult } from './utils/embedded-oauth';
 export { initializeInspectMode, isInspectModeEnabled, enableInspectMode, IKON_INSPECT_MODE_CHANGED_EVENT } from './utils/inspect-mode';
-export { getProxyTierParam, getTransportParam, getConnectParam, getSessionParam, getSameOriginParam, getDebugParam, getDebugOverlayParam, getInspectParam, getLangParam, getAudioParam, getVideoParam, getWebRtcParam, getIceTransportPolicyParam, getRetryParam, getSnapshotParam, getSignedOutParam, setSdkUrlParam, IKON_PARAM_PROXY, IKON_PARAM_TRANSPORT, IKON_PARAM_CONNECT, IKON_PARAM_SESSION, IKON_PARAM_SAME_ORIGIN, IKON_PARAM_DEBUG, IKON_PARAM_DEBUG_OVERLAY, IKON_PARAM_INSPECT, IKON_PARAM_LANG, IKON_PARAM_AUDIO, IKON_PARAM_VIDEO, IKON_PARAM_WEBRTC, IKON_PARAM_ICE_TRANSPORT, IKON_PARAM_RETRY, IKON_PARAM_SNAPSHOT, IKON_PARAM_SIGNED_OUT, IKON_PARAM_OAUTH_TOKEN, IKON_PARAM_OAUTH_CODE, IKON_PARAM_OAUTH_PROVIDER, IKON_PARAM_OAUTH_PKCE, type TransportFamily, type PinnedTransport, } from './utils/query-params';
+export { getProxyTierParam, getTransportParam, getConnectParam, getResumeHandoff, getSessionParam, getSameOriginParam, getDebugParam, getDebugOverlayParam, getInspectParam, getLangParam, getAudioParam, getVideoParam, getWebRtcParam, getIceTransportPolicyParam, getRetryParam, getSnapshotParam, getSignedOutParam, setSdkUrlParam, IKON_PARAM_PROXY, IKON_PARAM_TRANSPORT, IKON_PARAM_CONNECT, IKON_PARAM_SESSION, IKON_PARAM_SAME_ORIGIN, IKON_PARAM_DEBUG, IKON_PARAM_DEBUG_OVERLAY, IKON_PARAM_INSPECT, IKON_PARAM_LANG, IKON_PARAM_AUDIO, IKON_PARAM_VIDEO, IKON_PARAM_WEBRTC, IKON_PARAM_ICE_TRANSPORT, IKON_PARAM_RETRY, IKON_PARAM_SNAPSHOT, IKON_PARAM_SIGNED_OUT, IKON_PARAM_OAUTH_TOKEN, IKON_PARAM_OAUTH_CODE, IKON_PARAM_OAUTH_PROVIDER, IKON_PARAM_OAUTH_PKCE, type TransportFamily, type PinnedTransport, } from './utils/query-params';
 export type { HttpStreamMode } from './transport/transport';
 export { getOpcodeName } from './utils/opcode-names';
 export { initializeLogSink, setSendLogsCallback, getBufferedLogs, takeBufferedLogs, flushLogs, clearLogBuffer, getLogBufferSize } from './utils/log-sink';
@@ -34,7 +35,7 @@ export { loginErrorInterceptor, reprovisionAfterLogin, consumeLoginHandoff, getL
 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, deriveCrossOriginAuthUrl, getSameOriginAuthUrl, deriveBackendUrl, deriveBackendType, parseUrlParams, isCloudEnvironment, getUrlWithoutSession, type UrlParams } from './connection/urls';
 export { getOrCreateDeviceId, clearDeviceId, extractUserIdFromToken } from './storage';
-export { IkonMedia, IkonAudioPlayback, IkonVideoPlayback, VisemeTracker, isSharedArrayBufferSupported, isAudioWorkletSupported, IkonMediaCapture, IkonVideoCapture, IkonAudioCapture, IkonImageCapture, isMobileBrowserLikely } from './media';
-export type { IkonMediaConfig, IkonAudioPlaybackConfig, IkonVideoPlaybackConfig, IkonVideoCaptureHandle, IkonVideoCaptureRequest, IkonVideoCaptureOptions, VideoCaptureSource, IkonAudioCaptureHandle, IkonAudioCaptureRequest, IkonAudioCaptureOptions, IkonImageCaptureRequest, IkonImageCaptureResult, IkonNativeCameraCaptureRequest, IkonNativeCameraFacing } from './media';
+export { IkonMedia, IkonAudioPlayback, IkonVideoPlayback, VisemeTracker, isSharedArrayBufferSupported, isAudioWorkletSupported, IkonMediaCapture, IkonVideoCapture, IkonAudioCapture, IkonImageCapture, isMobileBrowserLikely, queryMediaPermission, requestMediaPermission, watchMediaPermission } from './media';
+export type { IkonMediaConfig, IkonAudioPlaybackConfig, IkonVideoPlaybackConfig, IkonVideoCaptureHandle, IkonVideoCaptureRequest, IkonVideoCaptureOptions, VideoCaptureSource, IkonAudioCaptureHandle, IkonAudioCaptureRequest, IkonAudioCaptureOptions, IkonImageCaptureRequest, IkonImageCaptureResult, IkonNativeCameraCaptureRequest, IkonNativeCameraFacing, MediaPermissionState, MediaPermissionKind } 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_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';