@ikonai/sdk 1.0.57 → 1.0.58

package/app-messaging.d.ts

@@ -0,0 +1,51 @@
+import { ProtocolMessage } from '../../../shared/protocol/src/index.ts';
+import { IkonClient } from './client/ikon-client';
+/**
+ * Describes one app-local Teleport message type, tying together the opcode and
+ * the encode/decode functions emitted by `ikon app teleport build` for a
+ * `Schema/*.tp` type. Build one from the generated module's exports, e.g.:
+ *
+ * ```ts
+ * import { STROKE_INPUT_OPCODE, toProtocolMessageStrokeInput, fromProtocolMessageStrokeInputAsync,
+ *          type StrokeInput } from './generated/protocol/stroke-input';
+ *
+ * const StrokeInputMessage: AppMessageType<StrokeInput> = {
+ *   opcode: STROKE_INPUT_OPCODE,
+ *   toProtocolMessage: toProtocolMessageStrokeInput,
+ *   fromProtocolMessage: fromProtocolMessageStrokeInputAsync,
+ * };
+ * ```
+ */
+export interface AppMessageType<T> {
+    /** The message's `GROUP_APP_LOCAL` opcode (the `X_OPCODE` constant). */
+    readonly opcode: number;
+    /** Generated `toProtocolMessageX` — encodes a native value into a wire message. */
+    toProtocolMessage(value: T, senderId: number): ProtocolMessage;
+    /** Generated `fromProtocolMessageXAsync` — decodes a wire message to the native value. */
+    fromProtocolMessage(message: ProtocolMessage): Promise<T> | T;
+}
+/** Handle returned by {@link AppMessaging.on}; call {@link close} to unsubscribe. */
+export interface AppMessageSubscription {
+    close(): void;
+}
+/**
+ * Typed app↔server custom-message helper, the browser counterpart of the C#
+ * `app.SendMessage<T>` / `app.OnMessage<T>`. Sends and receives an app's own
+ * `Schema/*.tp` types as native objects over the app-local Teleport channel
+ * (`GROUP_APP_LOCAL`) — no JSON marshalling. Use it for high-frequency side
+ * data (strokes, cursors, game state) alongside the declarative reactive UI.
+ */
+export declare class AppMessaging {
+    private readonly client;
+    constructor(client: IkonClient);
+    /** Send a typed app message to the server. */
+    send<T>(type: AppMessageType<T>, value: T): void;
+    /**
+     * Subscribe to inbound app messages of one type (filtered by its opcode).
+     * The handler receives the decoded native payload and the sender's session id.
+     * Dispose the returned handle to unsubscribe.
+     */
+    on<T>(type: AppMessageType<T>, handler: (payload: T, senderId: number) => void): AppMessageSubscription;
+}
+/** Create an {@link AppMessaging} helper bound to a client. */
+export declare function appMessaging(client: IkonClient): AppMessaging;

package/client/connection-state.d.ts

@@ -1,8 +1,23 @@
 /**
  * Connection state managed by IkonClient.
- * The SDK internally manages UI-related states with timers.
+ *
+ * Live states (currently emitted by the runtime):
+ * - `waitingForExternalConnectUrl` — preview mode, waiting for the parent window to post a connect URL.
+ * - `connecting` — actively trying to connect. The `isConnectingSlow` boolean on the React layer flips true after a timeout.
+ * - `connected` — successfully connected.
+ * - `reconnecting` — was connected, lost the socket, retrying.
+ * - `offline` — gave up. The companion `error` field (or `IkonClient.lastError`) carries an optional message.
+ *
+ * Deprecated states are kept in the union so existing string-equality checks in user code keep type-checking;
+ * the runtime no longer transitions into them.
  */
-export type ConnectionState = 'idle' | 'waitingForExternalConnectUrl' | 'connecting' | 'connectingSlow' | 'connected' | 'reconnecting' | 'offline' | 'offlineError';
+export type ConnectionState = 
+/** @deprecated No longer emitted. Initial state is now `connecting`. */
+'idle' | 'waitingForExternalConnectUrl' | 'connecting'
+/** @deprecated No longer emitted. Use `useIkonApp().isConnectingSlow` (boolean) instead. */
+ | 'connectingSlow' | 'connected' | 'reconnecting' | 'offline'
+/** @deprecated No longer emitted. Offline-with-error is now `offline` with the message on `useIkonApp().error`. */
+ | 'offlineError';
 /**
  * Check if the state indicates the client is actively trying to connect.
  */
@@ -12,10 +27,11 @@ export declare function isConnecting(state: ConnectionState): boolean;
  */
 export declare function isConnected(state: ConnectionState): boolean;
 /**
- * Check if the state indicates the client is offline (either normal or error).
+ * Check if the state indicates the client is offline.
  */
 export declare function isOffline(state: ConnectionState): boolean;
 /**
  * Check if the state indicates an error condition.
+ * @deprecated The runtime no longer emits `offlineError`. Read `useIkonApp().error` to detect offline-with-error.
  */
 export declare function isError(state: ConnectionState): boolean;

package/client/ikon-client.d.ts

@@ -66,7 +66,7 @@ export type StateHandler = (state: ConnectionState) => void;
  *
  * Features:
  * - Manages connection lifecycle
- * - Provides UI-friendly connection states (idle, connecting, connectingSlow, connected, offline, offlineError)
+ * - 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)
@@ -96,7 +96,7 @@ export declare class IkonClient {
     private authResponse;
     private _connectUrl;
     private currentState;
-    private slowConnectionTimer;
+    private _connectStarted;
     private connectionTimer;
     private messageSubscribers;
     private subscriberHandlers;
@@ -105,7 +105,14 @@ export declare class IkonClient {
     private stateSubscribers;
     private abortController;
     private readonly config;
-    private readonly slowConnectionThresholdMs;
+    private readonly _slowConnectionThresholdMs;
+    /**
+     * Time (ms) after which a still-`connecting` session should be considered "slow"
+     * by the React layer (see `useIkonApp().isConnectingSlow`). The SDK no longer
+     * transitions state for it — exposed here so the React timer can honor the
+     * config value if the host overrides it.
+     */
+    get slowConnectionThresholdMs(): number;
     private readonly connectionTimeoutMs;
     private readonly actionAckTimeoutMs;
     private readonly _pendingActionAcks;
@@ -203,8 +210,8 @@ export declare class IkonClient {
     constructor(config: IkonClientConfig);
     private _lastError;
     /**
-     * Get the error that caused 'offlineError' state, if any.
-     * Returns undefined if not in error state.
+     * Get the error that drove the client into the `offline` state, if any.
+     * Returns undefined when offline-without-error or when not in offline state.
      */
     get lastError(): Error | undefined;
     private _sessionId;
@@ -343,8 +350,9 @@ export declare class IkonClient {
      */
     private setState;
     /**
-     * Set the offlineError state with an associated error.
-     * Use this for unrecoverable SDK internal errors.
+     * Go offline with an associated error message stored on `lastError`.
+     * Used for unrecoverable SDK internal errors. The state itself is `offline`; the error
+     * is surfaced via the companion field so consumers don't need a separate state to handle.
      */
     private setErrorState;
     private connectProtocol;

package/index.d.ts

@@ -1,4 +1,5 @@
 export { IkonClient, 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 type { ConnectionState } from './client/connection-state';
 export { isConnecting, isConnected, isOffline, isError } from './client/connection-state';