@ikonai/sdk 0.0.7 → 0.0.9

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

@@ -217,6 +217,14 @@ export interface IkonClientConfig {
      * Can be async (return a Promise).
      */
     onReady?: () => void | Promise<void>;
+    /**
+     * Disable auto-registration of browser convenience functions.
+     * By default, functions like getTheme, setTheme, getLocation, etc. are
+     * automatically registered when running in a browser environment.
+     * Set to true to disable this behavior.
+     * Default: false
+     */
+    disableBrowserFunctions?: boolean;
 }
 export declare const DEFAULT_SLOW_CONNECTION_THRESHOLD_MS = 5000;
 export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 30000;

package/client/ikon-client.d.ts

@@ -1,4 +1,5 @@
 import { GlobalState, ProtocolMessage } from '../../../../shared/generated/src/index.ts';
+import { FunctionRegistry } from '../functions/function-registry';
 import { ConnectionState } from './connection-state';
 import { IkonClientConfig } from './ikon-client-config';
 /**
@@ -54,6 +55,8 @@ export declare class IkonClient {
     private boundVisibilityChange;
     private _globalState;
     private _initialGlobalStateReceived;
+    private readonly _functionRegistry;
+    private unregisterBrowserFunctions;
     constructor(config: IkonClientConfig);
     private _lastError;
     /**
@@ -76,6 +79,10 @@ export declare class IkonClient {
      * Get the current connection state.
      */
     get connectionState(): ConnectionState;
+    /**
+     * Get the function registry for registering custom functions.
+     */
+    get functionRegistry(): FunctionRegistry;
     /**
      * Connect to the Ikon server.
      * Returns when connected or throws if connection fails.
@@ -110,6 +117,10 @@ export declare class IkonClient {
      * Handle incoming protocol message from channel manager.
      */
     private handleProtocolMessage;
+    /**
+     * Notify config callback and message subscribers.
+     */
+    private notifyMessageSubscribers;
     /**
      * Handle channel manager state changes.
      */
@@ -151,12 +162,12 @@ export declare class IkonClient {
      */
     private handleVisibilityChange;
     /**
-     * Check if the connection is still healthy after tab was backgrounded.
+     * Check if the connection is still healthy after page was backgrounded.
      * If connection died while backgrounded, trigger reconnection.
      */
     private checkConnectionHealth;
     /**
-     * Handle connection ready - call user's onReady callback, then send ClientReady.
+     * Handle connection ready - attach function registry, call user's onReady callback, then send ClientReady.
      * Called on every connect (including reconnects).
      */
     private handleReady;

package/connection/authenticator.d.ts

@@ -33,10 +33,9 @@ export declare function authenticateLocal(config: LocalConfig, signal?: AbortSig
  * 1. Parse URL query parameters (id → sessionId, ck → channelKey, all → parameters)
  * 2. Derive backend URL and space domain from hostname
  * 3. Fetch space info by domain
- * 4. Fetch channels for space
- * 5. Select channel (by channelKey or first available)
- * 6. POST /rooms/connect and poll until running
- * 7. Connect to the returned Ikon server URL
+ * 4. Request channel
+ * 5. POST /rooms/connect and poll until running
+ * 6. Connect to the returned Ikon server URL
  */
 export declare function authenticateBrowser(config: BrowserConfig, signal?: AbortSignal): Promise<AuthResult>;
 /**
@@ -46,9 +45,8 @@ export declare function authenticateBrowser(config: BrowserConfig, signal?: Abor
  * 1. POST /auth/api-key with { space, apiKey, user } → get JWT token
  * 2. Use token as Bearer auth for backend requests
  * 3. GET /profiles/me?space={spaceId} to create user profile
- * 4. Fetch channels for space
- * 5. Select channel (by channelKey or first available)
- * 6. POST /rooms/connect and poll until running
- * 7. Connect to the returned Ikon server URL
+ * 4. Request channel
+ * 5. POST /rooms/connect and poll until running
+ * 6. Connect to the returned Ikon server URL
  */
 export declare function authenticateApiKey(config: ApiKeyConfig, signal?: AbortSignal): Promise<AuthResult>;

package/functions/browser-functions.d.ts

@@ -0,0 +1,10 @@
+import { FunctionRegistry } from './function-registry';
+/**
+ * Register all browser convenience functions with a registry.
+ * Returns an unregister function that removes all browser functions.
+ */
+export declare function registerBrowserFunctions(registry: FunctionRegistry): () => void;
+/**
+ * Check if browser environment is available.
+ */
+export declare function isBrowserEnvironment(): boolean;

package/functions/function-registry.d.ts

@@ -0,0 +1,75 @@
+import { ProtocolMessage } from '../../../../shared/generated/src/index.ts';
+import { FunctionDefinition, FunctionHandler, NormalizedFunction } from './types';
+export interface FunctionRegistryConfig {
+    sendProtocolMessage: (message: ProtocolMessage) => void;
+    sessionId: number;
+}
+export declare class FunctionRegistry {
+    private readonly functions;
+    private config;
+    private isConnected;
+    /**
+     * Attach the registry to a connected IkonClient.
+     * Called internally by IkonClient when connection is established.
+     */
+    attach(config: FunctionRegistryConfig): void;
+    /**
+     * Detach from the client (on disconnect).
+     */
+    detach(): void;
+    /**
+     * Register a function with the registry.
+     * If already connected, sends registration to server immediately.
+     */
+    register(definition: FunctionDefinition, handler: FunctionHandler): () => void;
+    /**
+     * Unregister a function by name.
+     */
+    unregister(name: string): boolean;
+    /**
+     * Check if a function is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * Get a registered function (for testing/inspection).
+     */
+    get(name: string): NormalizedFunction | undefined;
+    /**
+     * Get the number of registered functions.
+     */
+    get size(): number;
+    /**
+     * Handle incoming protocol message.
+     * Returns true if the message was handled.
+     */
+    handleProtocolMessage(message: ProtocolMessage, opcode: number): boolean;
+    /**
+     * Send registrations for all functions.
+     * Called when connection is established or re-established.
+     */
+    private sendAllRegistrations;
+    /**
+     * Send a single function registration.
+     */
+    private sendRegistration;
+    /**
+     * Handle an incoming function call.
+     */
+    private handleFunctionCall;
+    /**
+     * Execute a function and send the result.
+     */
+    private executeFunction;
+    /**
+     * Send ACK for a function call.
+     */
+    private sendAck;
+    /**
+     * Send function result.
+     */
+    private sendResult;
+    /**
+     * Send function error.
+     */
+    private sendError;
+}

package/functions/index.d.ts

@@ -0,0 +1,3 @@
+export type { ValueDescriptor, NormalizedValueDescriptor, PrimitiveValueKind, FunctionParameterDefinition, FunctionDefinition, FunctionHandler, } from './types';
+export { FunctionRegistry, type FunctionRegistryConfig } from './function-registry';
+export { registerBrowserFunctions, isBrowserEnvironment } from './browser-functions';

package/functions/type-conversion.d.ts

@@ -0,0 +1,7 @@
+import { FunctionDefinition, FunctionHandler, NormalizedFunction, NormalizedValueDescriptor, ValueDescriptor } from './types';
+export declare function normalizeDescriptor(descriptor: ValueDescriptor): NormalizedValueDescriptor;
+export declare function descriptorToTypeName(descriptor: NormalizedValueDescriptor): string;
+export declare function convertParameterFromJson(json: string | undefined, descriptor: NormalizedValueDescriptor): unknown;
+export declare function convertValueToJson(value: unknown, descriptor: NormalizedValueDescriptor): string;
+export declare function getDefaultValue(descriptor: NormalizedValueDescriptor): unknown;
+export declare function normalizeFunction(definition: FunctionDefinition, handler: FunctionHandler): NormalizedFunction;

package/functions/types.d.ts

@@ -0,0 +1,61 @@
+import { ActionFunctionRegister } from '../../../../shared/generated/src/index.ts';
+export type PrimitiveValueKind = 'boolean' | 'number' | 'string';
+type PrimitiveDescriptor = {
+    kind: PrimitiveValueKind;
+    nullable?: boolean;
+};
+type ArrayDescriptor = {
+    kind: 'array';
+    element: ValueDescriptor;
+    nullable?: boolean;
+};
+type DictionaryDescriptor = {
+    kind: 'dictionary';
+    keyType?: 'string' | 'int';
+    value: ValueDescriptor;
+    nullable?: boolean;
+};
+export type ValueDescriptor = PrimitiveDescriptor | ArrayDescriptor | DictionaryDescriptor;
+export type NormalizedValueDescriptor = {
+    kind: PrimitiveValueKind;
+    nullable: boolean;
+} | {
+    kind: 'array';
+    element: NormalizedValueDescriptor;
+    nullable: boolean;
+} | {
+    kind: 'dictionary';
+    keyType: 'string' | 'int';
+    value: NormalizedValueDescriptor;
+    nullable: boolean;
+};
+export interface FunctionParameterDefinition {
+    name: string;
+    type: ValueDescriptor;
+    defaultValue?: unknown;
+    description?: string;
+}
+export interface FunctionDefinition {
+    name: string;
+    description?: string;
+    inlineCall?: boolean;
+    callOnlyOnce?: boolean;
+    returnType: ValueDescriptor;
+    parameters?: FunctionParameterDefinition[];
+}
+export type FunctionHandler = (...parameters: unknown[]) => unknown | Promise<unknown>;
+export interface NormalizedFunctionParameter {
+    name: string;
+    descriptor: NormalizedValueDescriptor;
+    hasDefaultValue: boolean;
+    defaultValueJson: string;
+    description?: string;
+}
+export interface NormalizedFunction {
+    definition: FunctionDefinition;
+    handler: FunctionHandler;
+    registerPayload: ActionFunctionRegister;
+    parameters: NormalizedFunctionParameter[];
+    returnType: NormalizedValueDescriptor;
+}
+export {};

package/index.d.ts

@@ -14,3 +14,5 @@ export { setLogLevel, setLogSink, getLogLevel, getLogSink, createLogger, LogLeve
 export type { LogEntry, LogSink, Logger } from './utils/logger';
 export { initializeLogSink, setSendLogsCallback, getBufferedLogs, takeBufferedLogs, flushLogs, clearLogBuffer, getLogBufferSize } from './utils/logSink';
 export type { LogSinkConfig } from './utils/logSink';
+export { FunctionRegistry, registerBrowserFunctions, isBrowserEnvironment, type FunctionRegistryConfig } from './functions';
+export type { ValueDescriptor, NormalizedValueDescriptor, PrimitiveValueKind, FunctionParameterDefinition, FunctionDefinition, FunctionHandler } from './functions';