@ikonai/sdk 0.0.1

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@ikonai/sdk",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  }
+}

package/transport/transport.d.ts

@@ -0,0 +1,63 @@
+import { ProtocolMessage } from '../../../platform-generated/src/index.ts';
+/**
+ * Transport interface for Ikon server connections.
+ * Designed to support both WebSocket and WebTransport implementations.
+ */
+export interface Transport {
+    /**
+     * Connect to the server and authenticate with the provided auth ticket.
+     * @param uri - The WebSocket or WebTransport URI
+     * @param authTicket - Binary auth ticket to send immediately after connection
+     */
+    connect(uri: string, authTicket: Uint8Array): Promise<void>;
+    /**
+     * Send a protocol message to the server.
+     */
+    send(message: ProtocolMessage): void;
+    /**
+     * Close the connection gracefully.
+     */
+    close(): void;
+    /**
+     * Check if the transport is currently connected.
+     */
+    readonly isConnected: boolean;
+}
+/**
+ * Callbacks for transport events.
+ */
+export interface TransportCallbacks {
+    /**
+     * Called when a protocol message is received from the server.
+     * The SDK will handle keepalive internally; other messages are passed to this callback.
+     */
+    onProtocolMessage: (message: Uint8Array) => void;
+    /**
+     * Called when the connection is closed.
+     * @param reason - Optional reason for the close
+     * @param wasClean - Whether the close was clean (normal)
+     */
+    onClose: (reason?: string, wasClean?: boolean) => void;
+    /**
+     * Called when an error occurs.
+     */
+    onError: (error: Error) => void;
+}
+/**
+ * Configuration for creating a transport.
+ */
+export interface TransportConfig {
+    /**
+     * Callbacks for transport events.
+     */
+    callbacks: TransportCallbacks;
+    /**
+     * Timeout in milliseconds for keepalive detection.
+     * If no keepalive is received within this time, the connection is considered dead.
+     */
+    keepaliveTimeoutMs: number;
+    /**
+     * Session ID for protocol messages.
+     */
+    sessionId: number;
+}

package/transport/web-socket-transport.d.ts

@@ -0,0 +1,20 @@
+import { ProtocolMessage } from '../../../platform-generated/src/index.ts';
+import { Transport, TransportConfig } from './transport';
+/**
+ * WebSocket transport implementation for Ikon server connections.
+ */
+export declare class WebSocketTransport implements Transport {
+    private ws;
+    private keepaliveTimeout;
+    private readonly keepaliveTimeoutMs;
+    private readonly callbacks;
+    private readonly sessionId;
+    constructor(config: TransportConfig);
+    get isConnected(): boolean;
+    connect(uri: string, authTicket: Uint8Array): Promise<void>;
+    send(message: ProtocolMessage): void;
+    close(): void;
+    private handleProtocolMessage;
+    private resetKeepaliveTimeout;
+    private clearKeepaliveTimeout;
+}

package/transport/web-transport-transport.d.ts

@@ -0,0 +1,52 @@
+import { ProtocolMessage } from '../../../platform-generated/src/index.ts';
+import { Transport, TransportConfig } from './transport';
+/**
+ * Check if WebTransport is supported in the current environment.
+ */
+export declare function isWebTransportSupported(): boolean;
+/**
+ * WebTransport transport implementation for Ikon server connections.
+ *
+ * Uses a single bidirectional stream for reliable, ordered message delivery.
+ * This matches the WebSocket semantics expected by the Ikon protocol.
+ */
+export declare class WebTransportTransport implements Transport {
+    private transport;
+    private stream;
+    private reader;
+    private writer;
+    private keepaliveTimeout;
+    private readLoopActive;
+    private readonly keepaliveTimeoutMs;
+    private readonly callbacks;
+    private readonly sessionId;
+    constructor(config: TransportConfig);
+    get isConnected(): boolean;
+    connect(uri: string, authTicket: Uint8Array): Promise<void>;
+    send(message: ProtocolMessage): void;
+    close(): void;
+    /**
+     * Start the read loop to receive messages.
+     */
+    private startReadLoop;
+    /**
+     * Handle incoming protocol message.
+     */
+    private handleProtocolMessage;
+    /**
+     * Handle connection close.
+     */
+    private handleClose;
+    /**
+     * Reset the keepalive timeout.
+     */
+    private resetKeepaliveTimeout;
+    /**
+     * Clear the keepalive timeout.
+     */
+    private clearKeepaliveTimeout;
+    /**
+     * Clean up resources.
+     */
+    private cleanup;
+}

package/utils/logSink.d.ts

@@ -0,0 +1,60 @@
+import { LogEntry, LogLevel } from './logger';
+/**
+ * Configuration for the internal log sink.
+ */
+export interface LogSinkConfig {
+    /**
+     * Maximum number of log entries to buffer.
+     * Oldest entries are dropped when buffer is full.
+     * Default: 1000
+     */
+    maxBufferSize?: number;
+    /**
+     * Minimum log level to buffer (for sending to backend).
+     * Logs below this level are not buffered.
+     * Default: LogLevel.INFO
+     */
+    minLevel?: LogLevel;
+}
+/**
+ * Initialize the internal log sink.
+ * Called automatically when SDK is imported.
+ */
+export declare function initializeLogSink(config?: LogSinkConfig): void;
+/**
+ * Set the callback for sending logs to backend.
+ * When set, you can call flushLogs() to send buffered logs.
+ *
+ * @example
+ * ```typescript
+ * setSendLogsCallback((logs) => {
+ *   // Send logs to backend via your transport
+ *   connection.sendLogs(logs)
+ * })
+ * ```
+ */
+export declare function setSendLogsCallback(callback: ((logs: LogEntry[]) => void) | null): void;
+/**
+ * Get buffered logs without clearing the buffer.
+ */
+export declare function getBufferedLogs(): readonly LogEntry[];
+/**
+ * Get and clear buffered logs.
+ * Use this when you want to send logs and clear the buffer.
+ */
+export declare function takeBufferedLogs(): LogEntry[];
+/**
+ * Flush buffered logs to the backend via the send callback.
+ * Does nothing if no send callback is set or buffer is empty.
+ *
+ * @returns Number of logs flushed
+ */
+export declare function flushLogs(): number;
+/**
+ * Clear the log buffer without sending.
+ */
+export declare function clearLogBuffer(): void;
+/**
+ * Get the current buffer size.
+ */
+export declare function getLogBufferSize(): number;

package/utils/logger.d.ts

@@ -0,0 +1,69 @@
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    NONE = 4
+}
+/**
+ * Log entry structure for forwarding to backend.
+ */
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    levelName: string;
+    component: string;
+    message: string;
+    args: unknown[];
+}
+/**
+ * Log sink callback type.
+ * Called for every log message (regardless of log level filtering).
+ * The sink can decide what to do with the log (e.g., send to backend).
+ */
+export type LogSink = (entry: LogEntry) => void;
+/**
+ * Set the minimum log level for console output.
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Get the current log level.
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * Set a log sink to receive all log messages.
+ * Use this to forward logs to the backend.
+ * Pass null to remove the sink.
+ */
+export declare function setLogSink(sink: LogSink | null): void;
+/**
+ * Get the current log sink.
+ */
+export declare function getLogSink(): LogSink | null;
+/**
+ * Logger interface with component name.
+ */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Create a logger for a specific component.
+ *
+ * @param component - Component name (e.g., 'IkonClient', 'Connection', 'WebSocketTransport')
+ * @returns Logger instance with component name baked in
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger('MyComponent')
+ * logger.info('Starting up')  // [MyComponent] Starting up
+ * ```
+ */
+export declare function createLogger(component: string): Logger;
+/**
+ * Default logger for backwards compatibility.
+ * New code should use createLogger() with a component name.
+ */
+export declare const logger: Logger;