@principal-ai/control-tower-core 0.1.6 → 0.1.7

package/dist/server/BaseServer.d.ts

@@ -1,10 +1,11 @@
-import type { Event, Room, RoomConfig, Lock } from '../types/index.js';
+import type { Event, Room, RoomConfig, Lock, ExperimentalFeatureConfig, ExperimentalUsageEvent } from '../types/index.js';
 import type { ITransportAdapter } from '../abstractions/TransportAdapter.js';
 import type { IAuthAdapter } from '../abstractions/AuthAdapter.js';
 import type { IStorageAdapter } from '../abstractions/StorageAdapter.js';
 import type { RoomManager } from '../abstractions/RoomManager.js';
 import type { LockManager } from '../abstractions/LockManager.js';
 import { TypedEventEmitter } from '../abstractions/EventEmitter.js';
+import { ExperimentalAPI } from './ExperimentalAPI.js';
 import type { Server as HttpServer } from 'http';
 import type { Server as HttpsServer } from 'https';
 import type { WebSocketServer } from 'ws';
@@ -18,6 +19,7 @@ export interface ServerConfig {
     httpServer?: HttpServer | HttpsServer;
     webSocketPath?: string;
     webSocketServer?: WebSocketServer;
+    experimental?: ExperimentalFeatureConfig;
 }
 export interface ConnectedClient {
     id: string;
@@ -73,6 +75,7 @@ export interface ServerEvents {
         error: Error;
         context?: string;
     };
+    experimental_usage: ExperimentalUsageEvent;
     [key: string]: unknown;
 }
 export declare class BaseServer extends TypedEventEmitter<ServerEvents> {
@@ -87,6 +90,15 @@ export declare class BaseServer extends TypedEventEmitter<ServerEvents> {
     private running;
     private initialized;
     private mode;
+    /**
+     * Experimental APIs namespace
+     *
+     * ⚠️ WARNING: Experimental features are for development only.
+     * APIs may change or be removed without major version bumps.
+     *
+     * @see docs/EXPERIMENTAL_BROADCAST.md
+     */
+    readonly experimental: ExperimentalAPI;
     constructor(config: ServerConfig);
     start(port?: number): Promise<void>;
     initialize(): Promise<void>;

package/dist/server/BaseServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseServer.d.ts","sourceRoot":"","sources":["../../src/server/BaseServer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseServer.d.ts","sourceRoot":"","sources":["../../src/server/BaseServer.ts"],"names":[],"mappings":"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"}

package/dist/server/BaseServer.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseServer = void 0;
 const EventEmitter_js_1 = require("../abstractions/EventEmitter.js");
+const ExperimentalAPI_js_1 = require("./ExperimentalAPI.js");
 class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
     constructor(config) {
         super();
@@ -15,6 +16,20 @@ class BaseServer extends EventEmitter_js_1.TypedEventEmitter {
         this.storage = config.storage;
         this.roomManager = config.roomManager;
         this.lockManager = config.lockManager;
+        // Initialize experimental API namespace
+        this.experimental = new ExperimentalAPI_js_1.ExperimentalAPI({
+            config: config.experimental || {
+                enableBroadcast: false,
+                warnOnExperimentalUse: true,
+                trackUsageMetrics: false
+            },
+            logger: console,
+            emitMetric: (event) => {
+                void this.emit('experimental_usage', event);
+            },
+            getClients: () => Array.from(this.clients.values()),
+            sendToClient: (clientId, message) => this.sendToClient(clientId, message)
+        });
         // Determine mode based on configuration
         this.mode = (config.httpServer || config.webSocketServer) ? 'integration' : 'standalone';
         // Connect auth adapter to transport if both exist and transport supports it

package/dist/server/ExperimentalAPI.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Experimental Broadcast APIs
+ *
+ * ⚠️ DEVELOPMENT USE ONLY
+ *
+ * This namespace provides experimental broadcast methods for rapid prototyping
+ * and internal tooling. These APIs may change or be removed without major version bumps.
+ *
+ * For production use, submit a feature request to graduate these APIs to first-class APIs.
+ *
+ * @see docs/EXPERIMENTAL_BROADCAST.md
+ * @see docs/FEATURE_REQUEST_TEMPLATE.md
+ */
+import type { Message } from '../types/index.js';
+import type { ExperimentalFeatureConfig, ClientPredicate, BroadcastResult, BroadcastOptions, ExperimentalUsageEvent } from '../types/experimental.js';
+import type { ConnectedClient } from './BaseServer.js';
+/**
+ * Experimental API namespace
+ *
+ * Provides broadcast methods that bypass normal room isolation.
+ * Requires explicit opt-in via configuration.
+ */
+export declare class ExperimentalAPI {
+    private readonly config;
+    private readonly logger?;
+    private readonly emitMetric?;
+    private readonly getClients;
+    private readonly sendToClient;
+    constructor(options: {
+        config: ExperimentalFeatureConfig;
+        logger?: {
+            warn: (message: string, ...args: unknown[]) => void;
+        };
+        emitMetric?: (event: ExperimentalUsageEvent) => void;
+        getClients: () => ConnectedClient[];
+        sendToClient: (clientId: string, message: Record<string, unknown>) => Promise<void>;
+    });
+    /**
+     * Broadcasts a message to all connected clients
+     *
+     * ⚠️ WARNING: This bypasses room isolation and sends to every connected client.
+     *
+     * @experimental
+     * @param message - Message to broadcast
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * await server.experimental.broadcast({
+     *   type: 'system:announcement',
+     *   data: { message: 'Server maintenance in 5 minutes' }
+     * });
+     * ```
+     */
+    broadcast(message: Omit<Message, 'id' | 'timestamp'>, options?: BroadcastOptions): Promise<BroadcastResult>;
+    /**
+     * Broadcasts a message to all authenticated clients
+     *
+     * Skips unauthenticated connections. Useful for user-specific notifications.
+     *
+     * @experimental
+     * @param message - Message to broadcast
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * await server.experimental.broadcastAuthenticated({
+     *   type: 'presence:user_online',
+     *   data: { userId: 'alice', status: 'online' }
+     * });
+     * ```
+     */
+    broadcastAuthenticated(message: Omit<Message, 'id' | 'timestamp'>, options?: BroadcastOptions): Promise<BroadcastResult>;
+    /**
+     * Broadcasts a message to clients matching a predicate function
+     *
+     * Allows custom filtering logic for targeted broadcasts.
+     *
+     * @experimental
+     * @param predicate - Function to filter clients
+     * @param message - Message to broadcast
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * // Broadcast only to admin users
+     * await server.experimental.broadcastWhere(
+     *   (client) => getUserRole(client.userId) === 'admin',
+     *   {
+     *     type: 'admin:alert',
+     *     data: { message: 'Critical system event' }
+     *   }
+     * );
+     * ```
+     */
+    broadcastWhere(predicate: ClientPredicate, message: Omit<Message, 'id' | 'timestamp'>, options?: BroadcastOptions): Promise<BroadcastResult>;
+    /**
+     * Sends a message to specific users by their user IDs
+     *
+     * Useful for direct notifications and cross-room messaging.
+     *
+     * @experimental
+     * @param userIds - Array of user IDs to send to
+     * @param message - Message to send
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * await server.experimental.sendToUsers(
+     *   ['user123', 'user456'],
+     *   {
+     *     type: 'notification:mention',
+     *     data: { mentionedBy: 'alice', context: 'issue-42' }
+     *   }
+     * );
+     * ```
+     */
+    sendToUsers(userIds: string[], message: Omit<Message, 'id' | 'timestamp'>, options?: BroadcastOptions): Promise<BroadcastResult>;
+    private ensureEnabled;
+    private warnIfEnabled;
+    private trackUsage;
+    private broadcastToClients;
+    private generateId;
+}
+//# sourceMappingURL=ExperimentalAPI.d.ts.map

package/dist/server/ExperimentalAPI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExperimentalAPI.d.ts","sourceRoot":"","sources":["../../src/server/ExperimentalAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EACV,yBAAyB,EACzB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;GAKG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAA0D;IAClF,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAA0C;IACtE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwE;gBAEzF,OAAO,EAAE;QACnB,MAAM,EAAE,yBAAyB,CAAC;QAClC,MAAM,CAAC,EAAE;YAAE,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;SAAE,CAAC;QACjE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;QACrD,UAAU,EAAE,MAAM,eAAe,EAAE,CAAC;QACpC,YAAY,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KACrF;IAQD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,SAAS,CACb,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EAC1C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAa3B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,sBAAsB,CAC1B,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EAC1C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAa3B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,cAAc,CAClB,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EAC1C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAa3B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,WAAW,CACf,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,WAAW,CAAC,EAC1C,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC;IAgB3B,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,UAAU;YAmBJ,kBAAkB;IAsEhC,OAAO,CAAC,UAAU;CAGnB"}

package/dist/server/ExperimentalAPI.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * Experimental Broadcast APIs
+ *
+ * ⚠️ DEVELOPMENT USE ONLY
+ *
+ * This namespace provides experimental broadcast methods for rapid prototyping
+ * and internal tooling. These APIs may change or be removed without major version bumps.
+ *
+ * For production use, submit a feature request to graduate these APIs to first-class APIs.
+ *
+ * @see docs/EXPERIMENTAL_BROADCAST.md
+ * @see docs/FEATURE_REQUEST_TEMPLATE.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExperimentalAPI = void 0;
+const experimental_js_1 = require("../types/experimental.js");
+/**
+ * Experimental API namespace
+ *
+ * Provides broadcast methods that bypass normal room isolation.
+ * Requires explicit opt-in via configuration.
+ */
+class ExperimentalAPI {
+    constructor(options) {
+        this.config = options.config;
+        this.logger = options.logger;
+        this.emitMetric = options.emitMetric;
+        this.getClients = options.getClients;
+        this.sendToClient = options.sendToClient;
+    }
+    /**
+     * Broadcasts a message to all connected clients
+     *
+     * ⚠️ WARNING: This bypasses room isolation and sends to every connected client.
+     *
+     * @experimental
+     * @param message - Message to broadcast
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * await server.experimental.broadcast({
+     *   type: 'system:announcement',
+     *   data: { message: 'Server maintenance in 5 minutes' }
+     * });
+     * ```
+     */
+    async broadcast(message, options) {
+        this.ensureEnabled('broadcast', 'enableBroadcast');
+        this.warnIfEnabled('broadcast()');
+        const clients = this.getClients();
+        const result = await this.broadcastToClients(clients, message, options);
+        this.trackUsage('broadcast', message.type, clients.length, message.payload);
+        return result;
+    }
+    /**
+     * Broadcasts a message to all authenticated clients
+     *
+     * Skips unauthenticated connections. Useful for user-specific notifications.
+     *
+     * @experimental
+     * @param message - Message to broadcast
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * await server.experimental.broadcastAuthenticated({
+     *   type: 'presence:user_online',
+     *   data: { userId: 'alice', status: 'online' }
+     * });
+     * ```
+     */
+    async broadcastAuthenticated(message, options) {
+        this.ensureEnabled('broadcastAuthenticated', 'enableBroadcast');
+        this.warnIfEnabled('broadcastAuthenticated()');
+        const clients = this.getClients().filter(client => client.authenticated);
+        const result = await this.broadcastToClients(clients, message, options);
+        this.trackUsage('broadcastAuthenticated', message.type, clients.length, message.payload);
+        return result;
+    }
+    /**
+     * Broadcasts a message to clients matching a predicate function
+     *
+     * Allows custom filtering logic for targeted broadcasts.
+     *
+     * @experimental
+     * @param predicate - Function to filter clients
+     * @param message - Message to broadcast
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * // Broadcast only to admin users
+     * await server.experimental.broadcastWhere(
+     *   (client) => getUserRole(client.userId) === 'admin',
+     *   {
+     *     type: 'admin:alert',
+     *     data: { message: 'Critical system event' }
+     *   }
+     * );
+     * ```
+     */
+    async broadcastWhere(predicate, message, options) {
+        this.ensureEnabled('broadcastWhere', 'enableBroadcast');
+        this.warnIfEnabled('broadcastWhere()');
+        const clients = this.getClients().filter(predicate);
+        const result = await this.broadcastToClients(clients, message, options);
+        this.trackUsage('broadcastWhere', message.type, clients.length, message.payload);
+        return result;
+    }
+    /**
+     * Sends a message to specific users by their user IDs
+     *
+     * Useful for direct notifications and cross-room messaging.
+     *
+     * @experimental
+     * @param userIds - Array of user IDs to send to
+     * @param message - Message to send
+     * @param options - Broadcast options
+     * @returns Broadcast result with success/failure counts
+     *
+     * @throws {ExperimentalFeatureError} If experimental.enableBroadcast is not enabled
+     *
+     * @example
+     * ```typescript
+     * await server.experimental.sendToUsers(
+     *   ['user123', 'user456'],
+     *   {
+     *     type: 'notification:mention',
+     *     data: { mentionedBy: 'alice', context: 'issue-42' }
+     *   }
+     * );
+     * ```
+     */
+    async sendToUsers(userIds, message, options) {
+        this.ensureEnabled('sendToUsers', 'enableBroadcast');
+        this.warnIfEnabled('sendToUsers()');
+        const userIdSet = new Set(userIds);
+        const clients = this.getClients().filter(client => userIdSet.has(client.userId));
+        const result = await this.broadcastToClients(clients, message, options);
+        this.trackUsage('sendToUsers', message.type, clients.length, message.payload);
+        return result;
+    }
+    // Private helper methods
+    ensureEnabled(feature, configKey) {
+        if (!this.config[configKey]) {
+            throw new experimental_js_1.ExperimentalFeatureError(feature, configKey);
+        }
+    }
+    warnIfEnabled(method) {
+        if (this.config.warnOnExperimentalUse !== false) {
+            this.logger?.warn(`⚠️  Experimental API: server.experimental.${method} is for development only. ` +
+                `See docs/EXPERIMENTAL_BROADCAST.md for details.`);
+        }
+    }
+    trackUsage(method, messageType, recipientCount, payload) {
+        if (this.config.trackUsageMetrics && this.emitMetric) {
+            const payloadSize = payload ? JSON.stringify(payload).length : undefined;
+            this.emitMetric({
+                method,
+                messageType,
+                recipientCount,
+                timestamp: Date.now(),
+                payloadSize
+            });
+        }
+    }
+    async broadcastToClients(clients, message, options) {
+        const startTime = Date.now();
+        const opts = {
+            continueOnError: options?.continueOnError ?? true,
+            sendTimeout: options?.sendTimeout ?? 5000,
+            includeErrors: options?.includeErrors ?? false
+        };
+        const fullMessage = {
+            id: this.generateId(),
+            timestamp: Date.now(),
+            type: message.type,
+            payload: message.payload
+        };
+        let sent = 0;
+        let failed = 0;
+        const errors = [];
+        const sendPromises = clients.map(async (client) => {
+            try {
+                // Create timeout promise
+                const timeoutPromise = new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error('Send timeout')), opts.sendTimeout);
+                });
+                // Convert Message to Record<string, unknown> for sendToClient
+                const messageRecord = {
+                    id: fullMessage.id,
+                    type: fullMessage.type,
+                    payload: fullMessage.payload,
+                    timestamp: fullMessage.timestamp
+                };
+                // Race between send and timeout
+                await Promise.race([
+                    this.sendToClient(client.id, messageRecord),
+                    timeoutPromise
+                ]);
+                sent++;
+            }
+            catch (error) {
+                failed++;
+                if (opts.includeErrors) {
+                    errors.push({
+                        clientId: client.id,
+                        error: error
+                    });
+                }
+                if (!opts.continueOnError) {
+                    throw error;
+                }
+            }
+        });
+        await Promise.all(sendPromises);
+        return {
+            sent,
+            failed,
+            errors,
+            durationMs: Date.now() - startTime
+        };
+    }
+    generateId() {
+        return `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+}
+exports.ExperimentalAPI = ExperimentalAPI;

package/dist/server/ServerBuilder.d.ts

@@ -3,7 +3,7 @@ import type { IAuthAdapter } from '../abstractions/AuthAdapter.js';
 import type { IStorageAdapter } from '../abstractions/StorageAdapter.js';
 import type { RoomManager } from '../abstractions/RoomManager.js';
 import type { LockManager } from '../abstractions/LockManager.js';
-import type { RoomConfig } from '../types/index.js';
+import type { RoomConfig, ExperimentalFeatureConfig } from '../types/index.js';
 import { BaseServer } from './BaseServer.js';
 import type { Server as HttpServer } from 'http';
 import type { Server as HttpsServer } from 'https';
@@ -18,6 +18,7 @@ export declare class ServerBuilder {
     private httpServer?;
     private webSocketPath?;
     private webSocketServer?;
+    private experimentalFeatures?;
     withTransport(transport: ITransportAdapter): this;
     withAuth(auth: IAuthAdapter): this;
     withStorage(storage: IStorageAdapter): this;
@@ -27,6 +28,15 @@ export declare class ServerBuilder {
     withHttpServer(server: HttpServer | HttpsServer): this;
     withWebSocketPath(path: string): this;
     withWebSocketServer(wss: WebSocketServer): this;
+    /**
+     * Enable experimental features
+     *
+     * ⚠️ WARNING: Experimental features are for development only.
+     * APIs may change or be removed without major version bumps.
+     *
+     * @see docs/EXPERIMENTAL_BROADCAST.md
+     */
+    withExperimentalFeatures(features: ExperimentalFeatureConfig): this;
     build(): BaseServer;
 }
 //# sourceMappingURL=ServerBuilder.d.ts.map

package/dist/server/ServerBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ServerBuilder.d.ts","sourceRoot":"","sources":["../../src/server/ServerBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAqB,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAE1C,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAC,CAAoB;IACtC,OAAO,CAAC,IAAI,CAAC,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,iBAAiB,CAAC,CAAsB;IAChD,OAAO,CAAC,UAAU,CAAC,CAA2B;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAkB;IAE1C,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAKjD,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAKlC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK3C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAKxD,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAKtD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKrC,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAK/C,KAAK,IAAI,UAAU;CA+BpB"}
+{"version":3,"file":"ServerBuilder.d.ts","sourceRoot":"","sources":["../../src/server/ServerBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAC7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAqB,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,MAAM,CAAC;AACjD,OAAO,KAAK,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,OAAO,CAAC;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,IAAI,CAAC;AAE1C,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAC,CAAoB;IACtC,OAAO,CAAC,IAAI,CAAC,CAAe;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAkB;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,iBAAiB,CAAC,CAAsB;IAChD,OAAO,CAAC,UAAU,CAAC,CAA2B;IAC9C,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,eAAe,CAAC,CAAkB;IAC1C,OAAO,CAAC,oBAAoB,CAAC,CAA4B;IAEzD,aAAa,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAKjD,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAKlC,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI;IAK3C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C,eAAe,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK/C,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI;IAKxD,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,IAAI;IAKtD,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKrC,mBAAmB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAK/C;;;;;;;OAOG;IACH,wBAAwB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAKnE,KAAK,IAAI,UAAU;CAoCpB"}

package/dist/server/ServerBuilder.js

@@ -39,6 +39,18 @@ class ServerBuilder {
         this.webSocketServer = wss;
         return this;
     }
+    /**
+     * Enable experimental features
+     *
+     * ⚠️ WARNING: Experimental features are for development only.
+     * APIs may change or be removed without major version bumps.
+     *
+     * @see docs/EXPERIMENTAL_BROADCAST.md
+     */
+    withExperimentalFeatures(features) {
+        this.experimentalFeatures = features;
+        return this;
+    }
     build() {
         if (!this.transport) {
             throw new Error('Transport adapter is required');
@@ -62,7 +74,12 @@ class ServerBuilder {
             },
             httpServer: this.httpServer,
             webSocketPath: this.webSocketPath,
-            webSocketServer: this.webSocketServer
+            webSocketServer: this.webSocketServer,
+            experimental: this.experimentalFeatures || {
+                enableBroadcast: false,
+                warnOnExperimentalUse: true,
+                trackUsageMetrics: false
+            }
         };
         return new BaseServer_js_1.BaseServer(config);
     }

package/dist/server/index.d.ts

@@ -1,3 +1,4 @@
 export { BaseServer, type ServerConfig, type ServerEvents, type ConnectedClient } from './BaseServer.js';
 export { ServerBuilder } from './ServerBuilder.js';
+export { ExperimentalAPI } from './ExperimentalAPI.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/server/index.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServerBuilder = exports.BaseServer = void 0;
+exports.ExperimentalAPI = exports.ServerBuilder = exports.BaseServer = void 0;
 // Server-side implementations
 var BaseServer_js_1 = require("./BaseServer.js");
 Object.defineProperty(exports, "BaseServer", { enumerable: true, get: function () { return BaseServer_js_1.BaseServer; } });
 var ServerBuilder_js_1 = require("./ServerBuilder.js");
 Object.defineProperty(exports, "ServerBuilder", { enumerable: true, get: function () { return ServerBuilder_js_1.ServerBuilder; } });
+var ExperimentalAPI_js_1 = require("./ExperimentalAPI.js");
+Object.defineProperty(exports, "ExperimentalAPI", { enumerable: true, get: function () { return ExperimentalAPI_js_1.ExperimentalAPI; } });