@ikonai/sdk 0.0.1

package/channel/channel-manager.d.ts

@@ -0,0 +1,130 @@
+import { EndpointSelector } from '../client/endpoint-selector';
+import { Entrypoint, EntrypointType, ProtocolMessage } from '../../../platform-generated/src/index.ts';
+/**
+ * ChannelManager state.
+ */
+export type ChannelManagerState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'stopped' | 'offline';
+/**
+ * Configuration for ChannelManager.
+ */
+export interface ChannelManagerConfig {
+    /**
+     * Session ID from auth response.
+     */
+    sessionId: number;
+    /**
+     * Keepalive timeout in milliseconds.
+     */
+    keepaliveTimeoutMs: number;
+    /**
+     * Reconnect backoff in milliseconds.
+     */
+    reconnectBackoffMs: number;
+    /**
+     * Maximum reconnection attempts.
+     */
+    maxReconnectAttempts: number;
+    /**
+     * Endpoint selector for ordering types.
+     */
+    endpointSelector: EndpointSelector;
+    /**
+     * Callback when a protocol message is received from any channel.
+     */
+    onProtocolMessage?: (message: ProtocolMessage) => void;
+    /**
+     * Callback when state changes.
+     */
+    onStateChange?: (state: ChannelManagerState) => void;
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * ChannelManager orchestrates multiple channels to an Ikon server.
+ *
+ * Features:
+ * - Groups entrypoints by type
+ * - Tries types in order (WT → WS → WTProxy → WSProxy for prod)
+ * - Connects core channel first, then others in parallel
+ * - Handles reconnection with type fallback
+ * - Routes messages to/from appropriate channels
+ */
+export declare class ChannelManager {
+    private channels;
+    private activeType;
+    private state;
+    private reconnectAttempts;
+    private shouldReconnect;
+    private entrypoints;
+    private abortController;
+    private readonly config;
+    constructor(config: ChannelManagerConfig);
+    /**
+     * Get the current state.
+     */
+    get managerState(): ChannelManagerState;
+    /**
+     * Get the active endpoint type.
+     */
+    get activeEndpointType(): EntrypointType | null;
+    /**
+     * Connect to the server using the provided entrypoints.
+     */
+    connect(entrypoints: Entrypoint[]): Promise<void>;
+    /**
+     * Disconnect all channels.
+     */
+    disconnect(): void;
+    /**
+     * Send a protocol message to the appropriate channel.
+     * The opcode group is extracted from the message automatically.
+     */
+    sendProtocolMessage(message: ProtocolMessage): void;
+    /**
+     * Send a protocol message to all channels (for broadcast messages).
+     */
+    sendToAll(message: ProtocolMessage): void;
+    /**
+     * Internal connect implementation.
+     */
+    private connectInternal;
+    /**
+     * Connect all channels for a given endpoint type.
+     * Core channel connects first, then others in parallel.
+     */
+    private connectAllChannels;
+    /**
+     * Connect a single channel.
+     */
+    private connectChannel;
+    /**
+     * Group entrypoints by type.
+     */
+    private groupByType;
+    /**
+     * Handle channel state change.
+     */
+    private handleChannelStateChange;
+    /**
+     * Handle channel close.
+     */
+    private handleChannelClose;
+    /**
+     * Attempt to reconnect with exponential backoff.
+     */
+    private attemptReconnect;
+    /**
+     * Disconnect all channels.
+     */
+    private disconnectAll;
+    /**
+     * Update and notify state change.
+     */
+    private setState;
+    /**
+     * Delay with abort support.
+     */
+    private delay;
+}

package/channel/channel.d.ts

@@ -0,0 +1,102 @@
+import { Entrypoint, EntrypointType, ProtocolMessage } from '../../../platform-generated/src/index.ts';
+/**
+ * Channel state.
+ */
+export type ChannelState = 'disconnected' | 'connecting' | 'connected' | 'stopped';
+/**
+ * Configuration for a single channel.
+ */
+export interface ChannelConfig {
+    /**
+     * The entrypoint to connect to.
+     */
+    entrypoint: Entrypoint;
+    /**
+     * Session ID for the channel (from auth response).
+     */
+    sessionId: number;
+    /**
+     * Keepalive timeout in milliseconds.
+     */
+    keepaliveTimeoutMs: number;
+    /**
+     * Callback when a protocol message is received.
+     */
+    onProtocolMessage?: (message: ProtocolMessage) => void;
+    /**
+     * Callback when channel state changes.
+     */
+    onStateChange?: (state: ChannelState) => void;
+    /**
+     * Callback when channel is closed.
+     */
+    onClose?: (reason?: string, wasClean?: boolean) => void;
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: (error: Error) => void;
+}
+/**
+ * Channel manages a single transport connection to an Ikon server entrypoint.
+ *
+ * Features:
+ * - Connects to a specific entrypoint
+ * - Handles message routing
+ * - Detects server stopping
+ * - No reconnection logic (handled by ChannelManager)
+ */
+export declare class Channel {
+    private state;
+    private transport;
+    private readonly config;
+    private readonly entrypoint;
+    constructor(config: ChannelConfig);
+    /**
+     * Get the current channel state.
+     */
+    get channelState(): ChannelState;
+    /**
+     * Get the opcode groups this channel handles.
+     */
+    get opcodeGroups(): number;
+    /**
+     * Get the entrypoint type.
+     */
+    get type(): EntrypointType;
+    /**
+     * Check if transport is connected.
+     */
+    get isConnected(): boolean;
+    /**
+     * Connect to the entrypoint.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect the channel.
+     */
+    disconnect(): void;
+    /**
+     * Send a protocol message through the channel.
+     */
+    send(message: ProtocolMessage): void;
+    /**
+     * Connect the transport to the entrypoint.
+     */
+    private connectTransport;
+    /**
+     * Handle incoming protocol message.
+     */
+    private handleProtocolMessage;
+    /**
+     * Handle transport close.
+     */
+    private handleClose;
+    /**
+     * Handle transport error.
+     */
+    private handleError;
+    /**
+     * Update and notify state change.
+     */
+    private setState;
+}

package/channel/index.d.ts

@@ -0,0 +1,2 @@
+export { Channel, type ChannelConfig, type ChannelState } from './channel';
+export { ChannelManager, type ChannelManagerConfig, type ChannelManagerState } from './channel-manager';

package/client/connection-state.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Connection state managed by IkonClient.
+ * The SDK internally manages UI-related states with timers.
+ */
+export type ConnectionState = 'idle' | 'connecting' | 'connectingSlow' | 'connected' | 'reconnecting' | 'offline' | 'offlineError';
+/**
+ * Check if the state indicates the client is actively trying to connect.
+ */
+export declare function isConnecting(state: ConnectionState): boolean;
+/**
+ * Check if the state indicates the client is connected.
+ */
+export declare function isConnected(state: ConnectionState): boolean;
+/**
+ * Check if the state indicates the client is offline (either normal or error).
+ */
+export declare function isOffline(state: ConnectionState): boolean;
+/**
+ * Check if the state indicates an error condition.
+ */
+export declare function isError(state: ConnectionState): boolean;

package/client/endpoint-selector.d.ts

@@ -0,0 +1,34 @@
+import { Entrypoint, EntrypointType } from '../../../platform-generated/src/index.ts';
+import { LocalConfig } from './ikon-client-config';
+/**
+ * EndpointSelector handles ordering and selection of endpoint types.
+ *
+ * Behavior varies by environment:
+ * - Local: Use endpoints as-is from server (no ordering)
+ * - Cloud (browser/apiKey): Order by preference (WT → WS → WTProxy → WSProxy), remember working type
+ */
+export declare class EndpointSelector {
+    private readonly isLocal;
+    private workingEndpointType;
+    constructor(config: {
+        local?: LocalConfig;
+    });
+    /**
+     * Get ordered list of endpoint types to try.
+     * Returns only types that exist in the provided map.
+     */
+    getOrderedTypes(byType: Map<EntrypointType, Entrypoint[]>): EntrypointType[];
+    /**
+     * Remember the working endpoint type for future connections.
+     * Only stores in cloud mode.
+     */
+    rememberWorkingType(type: EntrypointType): void;
+    /**
+     * Clear the remembered endpoint type.
+     */
+    clearRememberedType(): void;
+    /**
+     * Load remembered type from localStorage.
+     */
+    private loadRememberedType;
+}

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

@@ -0,0 +1,226 @@
+import { ProtocolMessage } from '../../../platform-generated/src/index.ts';
+import { ConnectionState } from './connection-state';
+/**
+ * Backend environment type.
+ */
+export type BackendType = 'production' | 'development';
+/**
+ * Common connection options shared across all modes.
+ */
+export interface CommonConnectionConfig {
+    /**
+     * Device ID for the connection.
+     * If not provided, a random one will be generated.
+     */
+    deviceId?: string;
+    /**
+     * Product identifier.
+     */
+    productId?: string;
+    /**
+     * Version identifier.
+     */
+    versionId?: string;
+    /**
+     * User locale (e.g., 'en-US').
+     * Defaults to navigator.language or 'en-US'.
+     */
+    locale?: string;
+    /**
+     * Description for this client.
+     * Default: 'Ikon SDK TypeScript'
+     */
+    description?: string;
+    /**
+     * Launch parameters passed to the server.
+     */
+    parameters?: Record<string, string>;
+    /**
+     * Opcode groups to receive from server.
+     * Default: GROUP_CORE | GROUP_KEEPALIVE | GROUP_EVENTS | GROUP_ACTIONS | GROUP_UI | GROUP_AUDIO | GROUP_VIDEO
+     */
+    opcodeGroupsFromServer?: number;
+    /**
+     * Opcode groups to send to server.
+     * Default: GROUP_CORE | GROUP_KEEPALIVE | GROUP_EVENTS | GROUP_ACTIONS | GROUP_AUDIO | GROUP_VIDEO
+     */
+    opcodeGroupsToServer?: number;
+    /**
+     * Installation ID.
+     */
+    installId?: string;
+}
+/**
+ * Configuration for local development mode.
+ */
+export interface LocalConfig extends CommonConnectionConfig {
+    /**
+     * Host of the local Ikon server.
+     * Example: 'localhost'
+     */
+    host: string;
+    /**
+     * HTTPS port of the local Ikon server.
+     * Example: 8443
+     */
+    httpsPort: number;
+    /**
+     * User ID for the connection.
+     */
+    userId?: string;
+}
+/**
+ * Common options for cloud-based modes (browser and apiKey).
+ */
+export interface CloudConnectionConfig extends CommonConnectionConfig {
+    /**
+     * Optional channel key (slug) for spaces with multiple channels.
+     * If not provided, connects to the first available channel.
+     * Example: 'lobby' or 'main'
+     */
+    channelKey?: string;
+    /**
+     * Optional session hash for targeting precomputed sessions.
+     */
+    hash?: string;
+    /**
+     * Timeout for provisioning in milliseconds.
+     * Default: 60000 (60 seconds)
+     */
+    provisioningTimeoutMs?: number;
+}
+/**
+ * Configuration for browser authentication mode.
+ * Use this when the app is hosted on Ikon's domain and user is logged in via browser.
+ * Space is auto-discovered from the hostname subdomain.
+ * User identity comes from the browser session cookie.
+ */
+export interface BrowserConfig extends CloudConnectionConfig {
+}
+/**
+ * Configuration for API key authentication mode.
+ * Use this for programmatic/library access to cloud channels.
+ */
+export interface ApiKeyConfig extends CloudConnectionConfig {
+    /**
+     * API key for the space (from portal, format: 'ikon-xxxxx').
+     */
+    apiKey: string;
+    /**
+     * Space ID (MongoDB ObjectId from portal).
+     */
+    spaceId: string;
+    /**
+     * External user identifier - an arbitrary string to identify the user.
+     * This does not need to be an internal Ikon user ID.
+     * The backend will create/map an internal user for this external ID.
+     */
+    externalUserId: string;
+    /**
+     * Backend environment. Defaults to 'production'.
+     * - 'production' → https://api.prod.ikon.live
+     * - 'development' → https://api.dev.ikon.live
+     */
+    backendType?: BackendType;
+    /**
+     * User type for this connection.
+     * Use UserType enum values (e.g., UserType.Human, UserType.Agent).
+     * Default: UserType.Human
+     */
+    userType?: number;
+    /**
+     * Client type for this connection.
+     * Use ClientType enum values (e.g., ClientType.DesktopWeb, ClientType.Plugin).
+     * Default: ClientType.DesktopWeb
+     */
+    clientType?: number;
+}
+/**
+ * Timeout configuration for the SDK.
+ */
+export interface TimeoutConfig {
+    /**
+     * Duration in milliseconds before transitioning from 'connecting' to 'connectingSlow'.
+     * Default: 5000 (5 seconds)
+     */
+    slowConnectionThresholdMs?: number;
+    /**
+     * Duration in milliseconds before giving up and showing offline.
+     * Default: 30000 (30 seconds)
+     */
+    connectionTimeoutMs?: number;
+    /**
+     * Keepalive timeout in milliseconds.
+     * If no keepalive is received within this time, the connection is considered dead.
+     * Default: 125000 (125 seconds)
+     */
+    keepaliveTimeoutMs?: number;
+    /**
+     * Initial backoff for reconnection in milliseconds.
+     * Default: 1000 (1 second)
+     */
+    reconnectBackoffMs?: number;
+    /**
+     * Maximum number of reconnection attempts.
+     * Default: 5
+     */
+    maxReconnectAttempts?: number;
+}
+/**
+ * Configuration for IkonClient.
+ */
+export interface IkonClientConfig {
+    /**
+     * Local server configuration for development mode.
+     * Use this when connecting to a local Ikon server.
+     */
+    local?: LocalConfig;
+    /**
+     * Browser-based authentication.
+     * Use this when the app is hosted on Ikon's domain and user is logged in via browser.
+     * Space is auto-discovered from hostname subdomain.
+     */
+    browser?: BrowserConfig;
+    /**
+     * API key authentication for programmatic access.
+     * Use this for libraries, scripts, plugins that need to connect to cloud channels.
+     */
+    apiKey?: ApiKeyConfig;
+    /**
+     * Timeout configuration.
+     */
+    timeouts?: TimeoutConfig;
+    /**
+     * Callback when a protocol message is received.
+     * The SDK handles keepalive internally; other messages are passed to this callback.
+     * Use getOpcode(message) or readProtocolMessageHeaders(message) to extract details.
+     */
+    onProtocolMessage?: (message: ProtocolMessage) => void;
+    /**
+     * Callback when connection state changes.
+     */
+    onConnectionStateChange?: (state: ConnectionState) => void;
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Callback when tab visibility changes (browser only).
+     * Called when the tab is backgrounded or foregrounded.
+     * @param isVisible true when tab becomes visible, false when hidden
+     */
+    onVisibilityChange?: (isVisible: boolean) => void;
+    /**
+     * Called when connected to the server (including reconnects).
+     * Perform any initialization here. After this callback completes,
+     * the SDK sends ClientReady to the server.
+     * Can be async (return a Promise).
+     */
+    onReady?: () => void | Promise<void>;
+}
+export declare const DEFAULT_SLOW_CONNECTION_THRESHOLD_MS = 5000;
+export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 30000;
+export declare const DEFAULT_KEEPALIVE_TIMEOUT_MS = 125000;
+export declare const DEFAULT_RECONNECT_BACKOFF_MS = 500;
+export declare const DEFAULT_MAX_RECONNECT_ATTEMPTS = 6;
+export declare const DEFAULT_PROVISIONING_TIMEOUT_MS = 60000;

package/client/ikon-client.d.ts

@@ -0,0 +1,155 @@
+import { ProtocolMessage } from '../../../platform-generated/src/index.ts';
+import { ConnectionState } from './connection-state';
+import { IkonClientConfig } from './ikon-client-config';
+/**
+ * Protocol message handler callback type for subscribers.
+ */
+export type ProtocolMessageHandler = (message: ProtocolMessage) => void;
+/**
+ * State handler callback type for state subscribers.
+ */
+export type StateHandler = (state: ConnectionState) => void;
+/**
+ * IkonClient is the main entry point for connecting to an Ikon server.
+ *
+ * Features:
+ * - Manages connection lifecycle
+ * - Provides UI-friendly connection states (idle, connecting, connectingSlow, connected, offline, offlineError)
+ * - 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 authResponse;
+    private currentState;
+    private slowConnectionTimer;
+    private connectionTimer;
+    private messageSubscribers;
+    private stateSubscribers;
+    private abortController;
+    private readonly config;
+    private readonly slowConnectionThresholdMs;
+    private readonly connectionTimeoutMs;
+    private readonly endpointSelector;
+    private boundBeforeUnload;
+    private boundPageHide;
+    private boundVisibilityChange;
+    constructor(config: IkonClientConfig);
+    private _lastError;
+    /**
+     * Get the error that caused 'offlineError' state, if any.
+     * Returns undefined if not in error state.
+     */
+    get lastError(): Error | undefined;
+    private _sessionId;
+    /**
+     * Get the session ID from the server.
+     * Returns undefined if not connected.
+     */
+    get sessionId(): number | undefined;
+    /**
+     * Get the current connection state.
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Connect to the Ikon server.
+     * Returns when connected or throws if connection fails.
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnect from the server.
+     */
+    disconnect(): void;
+    /**
+     * Send a protocol message to the server.
+     * Routes to appropriate channel based on the message's opcode group.
+     */
+    sendProtocolMessage(message: ProtocolMessage): void;
+    /**
+     * Subscribe to protocol messages.
+     * Returns an unsubscribe function.
+     */
+    subscribeToProtocolMessages(handler: ProtocolMessageHandler): () => void;
+    /**
+     * Subscribe to connection state changes.
+     * Handler is called immediately with current state, then on every change.
+     * Returns an unsubscribe function.
+     */
+    subscribeToState(handler: StateHandler): () => void;
+    /**
+     * Authenticate with the server.
+     */
+    private authenticate;
+    /**
+     * Handle incoming protocol message from channel manager.
+     */
+    private handleProtocolMessage;
+    /**
+     * Handle channel manager state changes.
+     */
+    private handleChannelManagerStateChange;
+    /**
+     * Update the connection state and notify subscribers.
+     */
+    private setState;
+    /**
+     * Set the offlineError state with an associated error.
+     * Use this for unrecoverable SDK internal errors.
+     */
+    private setErrorState;
+    /**
+     * Clear all timers.
+     */
+    private clearTimers;
+    /**
+     * Set up browser lifecycle event handlers.
+     */
+    private setupLifecycleHandlers;
+    /**
+     * Clean up browser lifecycle event handlers.
+     */
+    private cleanupLifecycleHandlers;
+    /**
+     * Handle page beforeunload event.
+     * Close connection cleanly to avoid orphaned connections on the server.
+     */
+    private handleBeforeUnload;
+    /**
+     * Handle page hide event (mobile-friendly, bfcache compatible).
+     * Only disconnect if page is actually being unloaded (not persisted).
+     */
+    private handlePageHide;
+    /**
+     * Handle visibility change event.
+     * Check connection health when tab becomes visible again.
+     */
+    private handleVisibilityChange;
+    /**
+     * Check if the connection is still healthy after tab was backgrounded.
+     * If connection died while backgrounded, trigger reconnection.
+     */
+    private checkConnectionHealth;
+    /**
+     * Handle connection ready - call user's onReady callback, then send ClientReady.
+     * Called on every connect (including reconnects).
+     */
+    private handleReady;
+}