@xemahq/platform-common 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export * from './lib/biome-database';
 export * as Briefcase from './lib/briefcase/index';
 export * from './lib/deliverable-output-contract';
 export * from './lib/derive-required-workspace-slots';
+export * from './lib/edge-stream/index';
 export * from './lib/encryption';
 export * from './lib/envelope-encryption';
 export * from './lib/blind-index';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAIrC,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oCAAoC,CAAC;AACnD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AAIrC,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yBAAyB,CAAC;AACxC,cAAc,kBAAkB,CAAC;AACjC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,uBAAuB,CAAC;AACtC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,oCAAoC,CAAC;AACnD,cAAc,yBAAyB,CAAC;AAGxC,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,wBAAwB,CAAC;AAGvC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -43,6 +43,7 @@ __exportStar(require("./lib/biome-database"), exports);
 exports.Briefcase = __importStar(require("./lib/briefcase/index"));
 __exportStar(require("./lib/deliverable-output-contract"), exports);
 __exportStar(require("./lib/derive-required-workspace-slots"), exports);
+__exportStar(require("./lib/edge-stream/index"), exports);
 __exportStar(require("./lib/encryption"), exports);
 __exportStar(require("./lib/envelope-encryption"), exports);
 __exportStar(require("./lib/blind-index"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,sDAAoC;AACpC,sDAAoC;AACpC,uDAAqC;AAIrC,mEAAmD;AACnD,oEAAkD;AAClD,wEAAsD;AACtD,mDAAiC;AACjC,4DAA0C;AAC1C,oDAAkC;AAClC,+DAA6C;AAC7C,0DAAwC;AACxC,uDAAqC;AACrC,oDAAkC;AAClC,yDAAuC;AACvC,iEAA+C;AAC/C,wDAAsC;AACtC,4DAA0C;AAC1C,yDAAuC;AACvC,yDAAuC;AACvC,gEAA8C;AAC9C,sDAAoC;AACpC,2DAAyC;AACzC,uDAAqC;AACrC,wDAAsC;AACtC,4DAA0C;AAC1C,4DAA0C;AAC1C,wDAAsC;AACtC,4DAA0C;AAC1C,sDAAoC;AACpC,qDAAmC;AACnC,qEAAmD;AACnD,0DAAwC;AAGxC,kEAAgD;AAChD,uDAAqC;AACrC,2DAAyC;AACzC,4DAA0C;AAG1C,yDAAuC;AAGvC,uDAAqC;AAGrC,iDAA+B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAQA,sDAAoC;AACpC,sDAAoC;AACpC,uDAAqC;AAIrC,mEAAmD;AACnD,oEAAkD;AAClD,wEAAsD;AACtD,0DAAwC;AACxC,mDAAiC;AACjC,4DAA0C;AAC1C,oDAAkC;AAClC,+DAA6C;AAC7C,0DAAwC;AACxC,uDAAqC;AACrC,oDAAkC;AAClC,yDAAuC;AACvC,iEAA+C;AAC/C,wDAAsC;AACtC,4DAA0C;AAC1C,yDAAuC;AACvC,yDAAuC;AACvC,gEAA8C;AAC9C,sDAAoC;AACpC,2DAAyC;AACzC,uDAAqC;AACrC,wDAAsC;AACtC,4DAA0C;AAC1C,4DAA0C;AAC1C,wDAAsC;AACtC,4DAA0C;AAC1C,sDAAoC;AACpC,qDAAmC;AACnC,qEAAmD;AACnD,0DAAwC;AAGxC,kEAAgD;AAChD,uDAAqC;AACrC,2DAAyC;AACzC,4DAA0C;AAG1C,yDAAuC;AAGvC,uDAAqC;AAGrC,iDAA+B"}

package/dist/lib/edge-stream/edge-budget.d.ts

@@ -0,0 +1,5 @@
+export declare const EDGE_PROXY_READ_TIMEOUT_MS = 125000;
+export declare const EDGE_WEBSOCKET_IDLE_TIMEOUT_MS = 100000;
+export declare const SSE_HEARTBEAT_INTERVAL_MS = 20000;
+export declare const WS_PING_INTERVAL_MS = 25000;
+//# sourceMappingURL=edge-budget.d.ts.map

package/dist/lib/edge-stream/edge-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-budget.d.ts","sourceRoot":"","sources":["../../../src/lib/edge-stream/edge-budget.ts"],"names":[],"mappings":"AAqCA,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAOlD,eAAO,MAAM,8BAA8B,SAAU,CAAC;AAGtD,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAGhD,eAAO,MAAM,mBAAmB,QAAS,CAAC"}

package/dist/lib/edge-stream/edge-budget.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WS_PING_INTERVAL_MS = exports.SSE_HEARTBEAT_INTERVAL_MS = exports.EDGE_WEBSOCKET_IDLE_TIMEOUT_MS = exports.EDGE_PROXY_READ_TIMEOUT_MS = void 0;
+exports.EDGE_PROXY_READ_TIMEOUT_MS = 125_000;
+exports.EDGE_WEBSOCKET_IDLE_TIMEOUT_MS = 100_000;
+exports.SSE_HEARTBEAT_INTERVAL_MS = 20_000;
+exports.WS_PING_INTERVAL_MS = 25_000;
+//# sourceMappingURL=edge-budget.js.map

package/dist/lib/edge-stream/edge-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-budget.js","sourceRoot":"","sources":["../../../src/lib/edge-stream/edge-budget.ts"],"names":[],"mappings":";;;AAqCa,QAAA,0BAA0B,GAAG,OAAO,CAAC;AAOrC,QAAA,8BAA8B,GAAG,OAAO,CAAC;AAGzC,QAAA,yBAAyB,GAAG,MAAM,CAAC;AAGnC,QAAA,mBAAmB,GAAG,MAAM,CAAC"}

package/dist/lib/edge-stream/index.d.ts

@@ -0,0 +1,4 @@
+export * from './edge-budget';
+export * from './sse-stream';
+export * from './ws-keepalive';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/edge-stream/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/edge-stream/index.ts"],"names":[],"mappings":"AAUA,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}

package/dist/lib/edge-stream/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./edge-budget"), exports);
+__exportStar(require("./sse-stream"), exports);
+__exportStar(require("./ws-keepalive"), exports);
+//# sourceMappingURL=index.js.map

package/dist/lib/edge-stream/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/lib/edge-stream/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAUA,gDAA8B;AAC9B,+CAA6B;AAC7B,iDAA+B"}

package/dist/lib/edge-stream/sse-stream.d.ts

@@ -0,0 +1,20 @@
+import type { ServerResponse } from 'node:http';
+export type IsClosedFn = () => boolean;
+export declare function writeOrAwaitDrain(res: ServerResponse, chunk: string, isClosed: IsClosedFn): Promise<void>;
+export interface SseStreamOptions {
+    readonly heartbeatIntervalMs?: number;
+    readonly write?: (chunk: string) => void | Promise<void>;
+    readonly isClosed?: IsClosedFn;
+    readonly beat?: () => void | Promise<void>;
+    readonly onHeartbeatError?: (error: unknown) => void;
+}
+export interface SseStream {
+    readonly alive: () => boolean;
+    readonly comment: (text: string) => void;
+    readonly stop: () => void;
+}
+export declare function openSseStream(res: ServerResponse, options?: SseStreamOptions): SseStream;
+export declare function openSseRelay(res: ServerResponse, options: {
+    readonly heartbeatOwnedBy: string;
+}): void;
+//# sourceMappingURL=sse-stream.d.ts.map

package/dist/lib/edge-stream/sse-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-stream.d.ts","sourceRoot":"","sources":["../../../src/lib/edge-stream/sse-stream.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAYhD,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC;AAevC,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,cAAc,EACnB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,UAAU,GACnB,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED,MAAM,WAAW,gBAAgB;IAM/B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAMtC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzD,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAS/B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAQ3C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,SAAS;IAExB,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC;IAO9B,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAEzC,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;CAC3B;AAaD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,cAAc,EACnB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CA8FX;AAcD,wBAAgB,YAAY,CAC1B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE;IAAE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,GAC7C,IAAI,CAYN"}

package/dist/lib/edge-stream/sse-stream.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeOrAwaitDrain = writeOrAwaitDrain;
+exports.openSseStream = openSseStream;
+exports.openSseRelay = openSseRelay;
+const edge_budget_1 = require("./edge-budget");
+async function writeOrAwaitDrain(res, chunk, isClosed) {
+    if (isClosed() || res.writableEnded || res.destroyed) {
+        return;
+    }
+    const ok = res.write(chunk);
+    if (ok) {
+        return;
+    }
+    await new Promise((resolve) => {
+        const settle = () => {
+            res.removeListener('drain', settle);
+            res.removeListener('close', settle);
+            res.removeListener('error', settle);
+            resolve();
+        };
+        res.once('drain', settle);
+        res.once('close', settle);
+        res.once('error', settle);
+    });
+}
+const HEARTBEAT_COMMENT = 'heartbeat';
+function openSseStream(res, options = {}) {
+    const intervalMs = options.heartbeatIntervalMs ?? edge_budget_1.SSE_HEARTBEAT_INTERVAL_MS;
+    if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
+        throw new Error(`openSseStream: heartbeatIntervalMs must be a positive integer, received ${String(intervalMs)}.`);
+    }
+    if (intervalMs >= edge_budget_1.EDGE_WEBSOCKET_IDLE_TIMEOUT_MS) {
+        throw new Error(`openSseStream: heartbeatIntervalMs ${intervalMs}ms is at or above the ${edge_budget_1.EDGE_WEBSOCKET_IDLE_TIMEOUT_MS}ms edge idle window, so it cannot keep the stream alive. See edge-budget.ts.`);
+    }
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no');
+    res.flushHeaders();
+    res.socket?.setNoDelay(true);
+    const isClosed = options.isClosed ?? (() => false);
+    const write = options.write ??
+        ((chunk) => writeOrAwaitDrain(res, chunk, isClosed));
+    let stopped = false;
+    let timer;
+    const alive = () => !stopped && !res.writableEnded && !res.destroyed && !isClosed();
+    const stop = () => {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        if (timer !== undefined) {
+            clearInterval(timer);
+        }
+        res.removeListener('close', stop);
+        res.removeListener('error', stop);
+    };
+    timer = setInterval(() => {
+        if (!alive()) {
+            stop();
+            return;
+        }
+        try {
+            const result = options.beat
+                ? options.beat()
+                : write(`: ${HEARTBEAT_COMMENT}\n\n`);
+            if (result instanceof Promise) {
+                result.catch((error) => {
+                    stop();
+                    options.onHeartbeatError?.(error);
+                });
+            }
+        }
+        catch (error) {
+            stop();
+            options.onHeartbeatError?.(error);
+        }
+    }, intervalMs);
+    timer.unref?.();
+    res.once('close', stop);
+    res.once('error', stop);
+    const commentFn = (text) => {
+        if (/[\r\n]/.test(text)) {
+            throw new Error('SseStream.comment: an SSE comment must not contain CR or LF — it would end the comment and let the remainder parse as an event.');
+        }
+        if (!alive()) {
+            return;
+        }
+        const result = write(`: ${text}\n\n`);
+        if (result instanceof Promise) {
+            result.catch((error) => {
+                options.onHeartbeatError?.(error);
+            });
+        }
+    };
+    return { alive, comment: commentFn, stop };
+}
+function openSseRelay(res, options) {
+    if (options.heartbeatOwnedBy.trim().length === 0) {
+        throw new Error('openSseRelay: heartbeatOwnedBy must name the upstream whose heartbeat keeps this relay alive. A relay cannot beat for itself without corrupting forwarded frames.');
+    }
+    res.setHeader('Content-Type', 'text/event-stream');
+    res.setHeader('Cache-Control', 'no-cache, no-transform');
+    res.setHeader('Connection', 'keep-alive');
+    res.setHeader('X-Accel-Buffering', 'no');
+    res.flushHeaders();
+    res.socket?.setNoDelay(true);
+}
+//# sourceMappingURL=sse-stream.js.map

package/dist/lib/edge-stream/sse-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-stream.js","sourceRoot":"","sources":["../../../src/lib/edge-stream/sse-stream.ts"],"names":[],"mappings":"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"}

package/dist/lib/edge-stream/ws-keepalive.d.ts

@@ -0,0 +1,13 @@
+export interface WebSocketKeepaliveTarget {
+    readonly readyState: number;
+    ping(): void;
+}
+export interface WebSocketKeepaliveOptions {
+    readonly intervalMs?: number;
+    readonly onError?: (error: unknown) => void;
+}
+export interface WebSocketKeepalive {
+    readonly stop: () => void;
+}
+export declare function startWebSocketKeepalive(socket: WebSocketKeepaliveTarget, options?: WebSocketKeepaliveOptions): WebSocketKeepalive;
+//# sourceMappingURL=ws-keepalive.d.ts.map

package/dist/lib/edge-stream/ws-keepalive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-keepalive.d.ts","sourceRoot":"","sources":["../../../src/lib/edge-stream/ws-keepalive.ts"],"names":[],"mappings":"AAuBA,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IAExC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAM7B,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IAEjC,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;CAC3B;AAUD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,wBAAwB,EAChC,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CAoCpB"}

package/dist/lib/edge-stream/ws-keepalive.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWebSocketKeepalive = startWebSocketKeepalive;
+const edge_budget_1 = require("./edge-budget");
+const WEBSOCKET_OPEN = 1;
+function startWebSocketKeepalive(socket, options = {}) {
+    const intervalMs = options.intervalMs ?? edge_budget_1.WS_PING_INTERVAL_MS;
+    if (!Number.isInteger(intervalMs) || intervalMs <= 0) {
+        throw new Error(`startWebSocketKeepalive: intervalMs must be a positive integer, received ${String(intervalMs)}.`);
+    }
+    let stopped = false;
+    let timer;
+    const stop = () => {
+        if (stopped) {
+            return;
+        }
+        stopped = true;
+        if (timer !== undefined) {
+            clearInterval(timer);
+        }
+    };
+    timer = setInterval(() => {
+        if (socket.readyState !== WEBSOCKET_OPEN) {
+            stop();
+            return;
+        }
+        try {
+            socket.ping();
+        }
+        catch (error) {
+            stop();
+            options.onError?.(error);
+        }
+    }, intervalMs);
+    timer.unref?.();
+    return { stop };
+}
+//# sourceMappingURL=ws-keepalive.js.map

package/dist/lib/edge-stream/ws-keepalive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-keepalive.js","sourceRoot":"","sources":["../../../src/lib/edge-stream/ws-keepalive.ts"],"names":[],"mappings":";;AAoDA,0DAuCC;AA9ED,+CAAoD;AAOpD,MAAM,cAAc,GAAG,CAAC,CAAC;AAgCzB,SAAgB,uBAAuB,CACrC,MAAgC,EAChC,UAAqC,EAAE;IAEvC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,iCAAmB,CAAC;IAC7D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,4EAA4E,MAAM,CAAC,UAAU,CAAC,GAAG,CAClG,CAAC;IACJ,CAAC;IAED,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,KAAiD,CAAC;IAEtD,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO;QACT,CAAC;QACD,OAAO,GAAG,IAAI,CAAC;QACf,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,aAAa,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC,CAAC;IAEF,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;QACvB,IAAI,MAAM,CAAC,UAAU,KAAK,cAAc,EAAE,CAAC;YACzC,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,IAAI,CAAC;YACH,MAAM,CAAC,IAAI,EAAE,CAAC;QAChB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,EAAE,CAAC;YACP,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC,EAAE,UAAU,CAAC,CAAC;IACd,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAC;IAE5C,OAAO,EAAE,IAAI,EAAE,CAAC;AAClB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/platform-common",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Shared NestJS building blocks for Xema services — auth guards, response redaction, CORS configuration, and crypto helpers.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -26,7 +26,10 @@
     "@nestjs/platform-express": ">=10",
     "@nestjs/swagger": ">=7",
     "rxjs": ">=7",
-    "@xemahq/kernel-contracts": ">=0.57.0"
+    "@xemahq/kernel-contracts": ">=0.57.0",
+    "class-validator": ">=0.14",
+    "class-transformer": ">=0.5",
+    "reflect-metadata": ">=0.2"
   },
   "peerDependenciesMeta": {
     "@nestjs/platform-express": {
@@ -59,7 +62,7 @@
     "rxjs": "7.8.2",
     "ts-jest": "^29.4.9",
     "typescript": "5.9.3",
-    "@xemahq/kernel-contracts": "^0.57.0"
+    "@xemahq/kernel-contracts": "^0.58.0"
   },
   "exports": {
     ".": {