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

package/README.md

@@ -36,6 +36,7 @@ console.log('Server started on port 8080');
 - **Real-time Events**: Event broadcasting and history
 - **Extensible**: Abstract interfaces for custom implementations
 - **TypeScript**: Full type safety with generated declarations
+- **Experimental APIs**: Opt-in broadcast features for rapid prototyping (see [Experimental Features](#experimental-features))
 
 ## API Reference
 
@@ -79,6 +80,68 @@ class CustomRoomManager extends RoomManager {
 }
 ```
 
+## Experimental Features
+
+⚠️ **For Development Use Only**
+
+Control Tower Core provides experimental broadcast APIs for rapid prototyping and internal tooling. These APIs allow broadcasting messages beyond room boundaries.
+
+### Enabling Experimental Features
+
+```typescript
+import { ServerBuilder } from '@principal-ai/control-tower-core';
+
+const server = new ServerBuilder()
+  .withTransport(transportAdapter)
+  .withRoomManager(roomManager)
+  .withLockManager(lockManager)
+  .withExperimentalFeatures({
+    enableBroadcast: true  // Enable experimental broadcast APIs
+  })
+  .build();
+```
+
+### Using Experimental Broadcast
+
+```typescript
+// Broadcast to all connected clients
+await server.experimental.broadcast({
+  type: 'system:announcement',
+  data: { message: 'Server maintenance in 5 minutes' }
+});
+
+// Broadcast to authenticated users only
+await server.experimental.broadcastAuthenticated({
+  type: 'presence:user_online',
+  data: { userId: 'alice' }
+});
+
+// Broadcast with custom filtering
+await server.experimental.broadcastWhere(
+  (client) => client.userId.startsWith('admin_'),
+  { type: 'admin:alert', data: { ... } }
+);
+
+// Send to specific users
+await server.experimental.sendToUsers(
+  ['user1', 'user2'],
+  { type: 'notification:mention', data: { ... } }
+);
+```
+
+### Important Notes
+
+- **Experimental APIs may change or be removed** without major version bumps
+- **Not recommended for production** applications
+- Use for prototyping, then submit a [feature request](docs/FEATURE_REQUEST_TEMPLATE.md) to graduate to stable API
+- See [full documentation](docs/EXPERIMENTAL_BROADCAST.md) for details
+
+## Documentation
+
+- [Experimental Broadcast APIs](docs/EXPERIMENTAL_BROADCAST.md)
+- [Feature Request Template](docs/FEATURE_REQUEST_TEMPLATE.md)
+- [Architecture Design](DESIGN.md)
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { EventType, BaseEvent, FileAction, FileChangeEvent, GitStatusEvent, CommitEvent, BranchChangeEvent, CursorPositionEvent, Event, TokenPayload, AuthResult, CredentialType, OAuthProvider, Credentials, JWTConfig, OAuthConfig, AuthProvider, RoomPermission, Room, RoomUser, UserStatus, RoomState, RoomConfig, LockType, LockPriority, Lock, LockRequest, LockQueueItem, LockState, ConnectionState, ConnectionOptions, Message, MessageHandler, ErrorHandler, CloseHandler } from './types/index.js';
+export { EventType, BaseEvent, FileAction, FileChangeEvent, GitStatusEvent, CommitEvent, BranchChangeEvent, CursorPositionEvent, Event, TokenPayload, AuthResult, CredentialType, OAuthProvider, Credentials, JWTConfig, OAuthConfig, AuthProvider, RoomPermission, Room, RoomUser, UserStatus, RoomState, RoomConfig, LockType, LockPriority, Lock, LockRequest, LockQueueItem, LockState, ConnectionState, ConnectionOptions, Message, MessageHandler, ErrorHandler, CloseHandler, ExperimentalFeatureConfig, ClientPredicate, BroadcastResult, BroadcastOptions, ExperimentalUsageEvent, ExperimentalFeatureError } from './types/index.js';
 export { ITransportAdapter, IStorageAdapter, StorageOperation, IAuthAdapter, TypedEventEmitter, EventListener, UnsubscribeFn, RoomManager, LockManager, DefaultRoomManager, DefaultLockManager } from './abstractions/index.js';
 export { MockTransportAdapter, MockStorageAdapter, MockAuthAdapter } from './adapters/mock/index.js';
 export { WebSocketTransportAdapter, type WebSocketTransportConfig } from './adapters/websocket/index.js';
 export { BaseClient, ClientBuilder, type ClientConfig, type ClientEvents } from './client/index.js';
-export { BaseServer, ServerBuilder, type ServerConfig, type ServerEvents, type ConnectedClient } from './server/index.js';
+export { BaseServer, ServerBuilder, ExperimentalAPI, type ServerConfig, type ServerEvents, type ConnectedClient } from './server/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,SAAS,EACT,SAAS,EACT,UAAU,EACV,eAAe,EACf,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,EAEL,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EAEZ,cAAc,EACd,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EAEV,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,aAAa,EACb,SAAS,EAET,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,yBAAyB,EACzB,KAAK,wBAAwB,EAC9B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,UAAU,EACV,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,UAAU,EACV,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,SAAS,EACT,SAAS,EACT,UAAU,EACV,eAAe,EACf,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,EAEL,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EAEZ,cAAc,EACd,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EAEV,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,aAAa,EACb,SAAS,EAET,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,cAAc,EACd,YAAY,EACZ,YAAY,EAEZ,yBAAyB,EACzB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,EACzB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,yBAAyB,EACzB,KAAK,wBAAwB,EAC9B,MAAM,+BAA+B,CAAC;AAGvC,OAAO,EACL,UAAU,EACV,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -1,25 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ServerBuilder = exports.BaseServer = exports.ClientBuilder = exports.BaseClient = exports.WebSocketTransportAdapter = exports.MockAuthAdapter = exports.MockStorageAdapter = exports.MockTransportAdapter = exports.DefaultLockManager = exports.DefaultRoomManager = exports.LockManager = exports.RoomManager = exports.TypedEventEmitter = void 0;
+exports.ExperimentalAPI = exports.ServerBuilder = exports.BaseServer = exports.ClientBuilder = exports.BaseClient = exports.WebSocketTransportAdapter = exports.MockAuthAdapter = exports.MockStorageAdapter = exports.MockTransportAdapter = exports.DefaultLockManager = exports.DefaultRoomManager = exports.LockManager = exports.RoomManager = exports.TypedEventEmitter = exports.ExperimentalFeatureError = void 0;
+// Types
+var index_js_1 = require("./types/index.js");
+Object.defineProperty(exports, "ExperimentalFeatureError", { enumerable: true, get: function () { return index_js_1.ExperimentalFeatureError; } });
 // Abstractions
-var index_js_1 = require("./abstractions/index.js");
-Object.defineProperty(exports, "TypedEventEmitter", { enumerable: true, get: function () { return index_js_1.TypedEventEmitter; } });
-Object.defineProperty(exports, "RoomManager", { enumerable: true, get: function () { return index_js_1.RoomManager; } });
-Object.defineProperty(exports, "LockManager", { enumerable: true, get: function () { return index_js_1.LockManager; } });
-Object.defineProperty(exports, "DefaultRoomManager", { enumerable: true, get: function () { return index_js_1.DefaultRoomManager; } });
-Object.defineProperty(exports, "DefaultLockManager", { enumerable: true, get: function () { return index_js_1.DefaultLockManager; } });
+var index_js_2 = require("./abstractions/index.js");
+Object.defineProperty(exports, "TypedEventEmitter", { enumerable: true, get: function () { return index_js_2.TypedEventEmitter; } });
+Object.defineProperty(exports, "RoomManager", { enumerable: true, get: function () { return index_js_2.RoomManager; } });
+Object.defineProperty(exports, "LockManager", { enumerable: true, get: function () { return index_js_2.LockManager; } });
+Object.defineProperty(exports, "DefaultRoomManager", { enumerable: true, get: function () { return index_js_2.DefaultRoomManager; } });
+Object.defineProperty(exports, "DefaultLockManager", { enumerable: true, get: function () { return index_js_2.DefaultLockManager; } });
 // Adapters
-var index_js_2 = require("./adapters/mock/index.js");
-Object.defineProperty(exports, "MockTransportAdapter", { enumerable: true, get: function () { return index_js_2.MockTransportAdapter; } });
-Object.defineProperty(exports, "MockStorageAdapter", { enumerable: true, get: function () { return index_js_2.MockStorageAdapter; } });
-Object.defineProperty(exports, "MockAuthAdapter", { enumerable: true, get: function () { return index_js_2.MockAuthAdapter; } });
-var index_js_3 = require("./adapters/websocket/index.js");
-Object.defineProperty(exports, "WebSocketTransportAdapter", { enumerable: true, get: function () { return index_js_3.WebSocketTransportAdapter; } });
+var index_js_3 = require("./adapters/mock/index.js");
+Object.defineProperty(exports, "MockTransportAdapter", { enumerable: true, get: function () { return index_js_3.MockTransportAdapter; } });
+Object.defineProperty(exports, "MockStorageAdapter", { enumerable: true, get: function () { return index_js_3.MockStorageAdapter; } });
+Object.defineProperty(exports, "MockAuthAdapter", { enumerable: true, get: function () { return index_js_3.MockAuthAdapter; } });
+var index_js_4 = require("./adapters/websocket/index.js");
+Object.defineProperty(exports, "WebSocketTransportAdapter", { enumerable: true, get: function () { return index_js_4.WebSocketTransportAdapter; } });
 // Client
-var index_js_4 = require("./client/index.js");
-Object.defineProperty(exports, "BaseClient", { enumerable: true, get: function () { return index_js_4.BaseClient; } });
-Object.defineProperty(exports, "ClientBuilder", { enumerable: true, get: function () { return index_js_4.ClientBuilder; } });
+var index_js_5 = require("./client/index.js");
+Object.defineProperty(exports, "BaseClient", { enumerable: true, get: function () { return index_js_5.BaseClient; } });
+Object.defineProperty(exports, "ClientBuilder", { enumerable: true, get: function () { return index_js_5.ClientBuilder; } });
 // Server
-var index_js_5 = require("./server/index.js");
-Object.defineProperty(exports, "BaseServer", { enumerable: true, get: function () { return index_js_5.BaseServer; } });
-Object.defineProperty(exports, "ServerBuilder", { enumerable: true, get: function () { return index_js_5.ServerBuilder; } });
+var index_js_6 = require("./server/index.js");
+Object.defineProperty(exports, "BaseServer", { enumerable: true, get: function () { return index_js_6.BaseServer; } });
+Object.defineProperty(exports, "ServerBuilder", { enumerable: true, get: function () { return index_js_6.ServerBuilder; } });
+Object.defineProperty(exports, "ExperimentalAPI", { enumerable: true, get: function () { return index_js_6.ExperimentalAPI; } });