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

package/dist/types/experimental.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Experimental API Types
+ *
+ * ⚠️ WARNING: Types in this file are experimental and may change or be removed
+ * without major version bumps. Use only for prototyping and internal tooling.
+ *
+ * For production use, submit a feature request to graduate these APIs:
+ * @see docs/FEATURE_REQUEST_TEMPLATE.md
+ */
+import type { ConnectedClient } from '../server/BaseServer.js';
+/**
+ * Configuration for experimental features
+ */
+export interface ExperimentalFeatureConfig {
+    /**
+     * Enable experimental broadcast APIs
+     *
+     * ⚠️ DEVELOPMENT USE ONLY
+     * Allows use of server.experimental.broadcast() and related methods
+     *
+     * @default false
+     */
+    enableBroadcast?: boolean;
+    /**
+     * Enable runtime warnings for experimental API usage
+     *
+     * When true, logs warnings each time an experimental API is called
+     * Useful for tracking experimental API usage in development
+     *
+     * @default true
+     */
+    warnOnExperimentalUse?: boolean;
+    /**
+     * Track experimental API usage metrics
+     *
+     * When true, emits events for experimental API calls that can be
+     * monitored to understand usage patterns
+     *
+     * @default false
+     */
+    trackUsageMetrics?: boolean;
+}
+/**
+ * Client predicate function for filtering broadcasts
+ *
+ * @param client - The connected client to evaluate
+ * @returns true if the client should receive the broadcast
+ *
+ * @example
+ * // Broadcast only to admin users
+ * const isAdmin: ClientPredicate = (client) => {
+ *   return getUserRole(client.userId) === 'admin';
+ * };
+ */
+export type ClientPredicate = (client: ConnectedClient) => boolean;
+/**
+ * Result of a broadcast operation
+ */
+export interface BroadcastResult {
+    /**
+     * Number of clients that successfully received the message
+     */
+    sent: number;
+    /**
+     * Number of clients that failed to receive the message
+     */
+    failed: number;
+    /**
+     * Errors that occurred during broadcast
+     */
+    errors: Array<{
+        clientId: string;
+        error: Error;
+    }>;
+    /**
+     * Total time taken to complete the broadcast (milliseconds)
+     */
+    durationMs: number;
+}
+/**
+ * Options for broadcast operations
+ */
+export interface BroadcastOptions {
+    /**
+     * Whether to continue broadcasting even if some sends fail
+     *
+     * @default true
+     */
+    continueOnError?: boolean;
+    /**
+     * Timeout for each individual send operation (milliseconds)
+     *
+     * @default 5000
+     */
+    sendTimeout?: number;
+    /**
+     * Whether to include detailed error information in the result
+     *
+     * @default false
+     */
+    includeErrors?: boolean;
+}
+/**
+ * Experimental API usage metrics event
+ */
+export interface ExperimentalUsageEvent {
+    /**
+     * The experimental method that was called
+     */
+    method: 'broadcast' | 'broadcastAuthenticated' | 'broadcastWhere' | 'sendToUsers';
+    /**
+     * Message type being broadcast
+     */
+    messageType: string;
+    /**
+     * Number of recipients
+     */
+    recipientCount: number;
+    /**
+     * Timestamp of the call
+     */
+    timestamp: number;
+    /**
+     * Size of the message payload (bytes)
+     */
+    payloadSize?: number;
+}
+/**
+ * Error thrown when experimental features are not enabled
+ */
+export declare class ExperimentalFeatureError extends Error {
+    readonly feature: string;
+    readonly configKey: keyof ExperimentalFeatureConfig;
+    constructor(feature: string, configKey: keyof ExperimentalFeatureConfig);
+}
+//# sourceMappingURL=experimental.d.ts.map

package/dist/types/experimental.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"experimental.d.ts","sourceRoot":"","sources":["../../src/types/experimental.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;;;;OAOG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,eAAe,KAAK,OAAO,CAAC;AAEnE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,KAAK,CAAC;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,KAAK,CAAC;KACd,CAAC,CAAC;IAEH;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,MAAM,EAAE,WAAW,GAAG,wBAAwB,GAAG,gBAAgB,GAAG,aAAa,CAAC;IAElF;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;aAE/B,OAAO,EAAE,MAAM;aACf,SAAS,EAAE,MAAM,yBAAyB;gBAD1C,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,yBAAyB;CAe7D"}

package/dist/types/experimental.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * Experimental API Types
+ *
+ * ⚠️ WARNING: Types in this file are experimental and may change or be removed
+ * without major version bumps. Use only for prototyping and internal tooling.
+ *
+ * For production use, submit a feature request to graduate these APIs:
+ * @see docs/FEATURE_REQUEST_TEMPLATE.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExperimentalFeatureError = void 0;
+/**
+ * Error thrown when experimental features are not enabled
+ */
+class ExperimentalFeatureError extends Error {
+    constructor(feature, configKey) {
+        super(`Experimental feature '${feature}' is not enabled.\n\n` +
+            `To enable, set '${String(configKey)}: true' in your server configuration:\n\n` +
+            `  const server = new ServerBuilder()\n` +
+            `    .withExperimentalFeatures({ ${String(configKey)}: true })\n` +
+            `    .build();\n\n` +
+            `⚠️  WARNING: Experimental APIs are for development only.\n` +
+            `For production use, submit a feature request:\n` +
+            `https://github.com/your-org/control-tower-core/issues/new\n\n` +
+            `See docs/EXPERIMENTAL_BROADCAST.md for details.`);
+        this.feature = feature;
+        this.configKey = configKey;
+        this.name = 'ExperimentalFeatureError';
+    }
+}
+exports.ExperimentalFeatureError = ExperimentalFeatureError;

package/dist/types/index.d.ts

@@ -20,4 +20,5 @@ export interface Message {
 export type MessageHandler = (message: Message) => void | Promise<void>;
 export type ErrorHandler = (error: Error) => void;
 export type CloseHandler = (code: number, reason: string) => void;
+export { ExperimentalFeatureConfig, ClientPredicate, BroadcastResult, BroadcastOptions, ExperimentalUsageEvent, ExperimentalFeatureError } from './experimental.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,SAAS,EACT,UAAU,EACV,eAAe,EACf,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,EACN,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACb,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,aAAa,EACb,SAAS,EACV,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,eAAe,GAAG,cAAc,CAAC;AAE5F,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,SAAS,EACT,UAAU,EACV,eAAe,EACf,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,EACN,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,YAAY,EACZ,UAAU,EACV,cAAc,EACd,aAAa,EACb,WAAW,EACX,SAAS,EACT,WAAW,EACX,YAAY,EACb,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,cAAc,EACd,IAAI,EACJ,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACX,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,QAAQ,EACR,YAAY,EACZ,IAAI,EACJ,WAAW,EACX,aAAa,EACb,SAAS,EACV,MAAM,WAAW,CAAC;AAEnB,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,WAAW,GAAG,eAAe,GAAG,cAAc,CAAC;AAE5F,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AACxE,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAElE,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACtB,wBAAwB,EACzB,MAAM,mBAAmB,CAAC"}

package/dist/types/index.js

@@ -1,2 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExperimentalFeatureError = void 0;
+var experimental_js_1 = require("./experimental.js");
+Object.defineProperty(exports, "ExperimentalFeatureError", { enumerable: true, get: function () { return experimental_js_1.ExperimentalFeatureError; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/control-tower-core",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Centralized, runtime-agnostic library for real-time collaboration and synchronization",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",