@camera.ui/transport 0.0.1

package/dist/transports/socketio.d.ts

@@ -0,0 +1,19 @@
+import { Manager, Socket } from 'socket.io-client';
+import { TransportSpec } from '../core/types.js';
+import { Transport } from './contract.js';
+export type { Socket };
+export interface SocketioTransportOptions {
+    readonly spec?: Partial<TransportSpec>;
+    readonly path?: string;
+    readonly mainNamespace?: string;
+    readonly reconnection?: boolean;
+    readonly reconnectionDelay?: number;
+    readonly reconnectionDelayMax?: number;
+    readonly timeout?: number;
+}
+export interface SocketioTransport extends Transport {
+    readonly manager: Manager | null;
+    socket(namespace?: string): Socket | null;
+    ensureSocket(namespace: string): Socket | null;
+}
+export declare function createSocketioTransport(options?: SocketioTransportOptions): SocketioTransport;

package/dist/transports/socketio.js

@@ -0,0 +1,160 @@
+import { n as isEndpointChange, r as isSameTarget, t as TransportEmitter } from "../contract-d-0gfY8v.js";
+import { Manager, io } from "socket.io-client";
+//#region src/transports/socketio.ts
+var SOCKETIO_SPEC = {
+	id: "socketio",
+	kind: "persistent",
+	phaseGating: true,
+	graceMs: 4e3
+};
+function createSocketioTransport(options = {}) {
+	const spec = {
+		...SOCKETIO_SPEC,
+		...options.spec
+	};
+	const path = options.path ?? "/api/socket.io";
+	const mainNs = options.mainNamespace ?? "/camera.ui";
+	const reconnection = options.reconnection ?? true;
+	const reconnectionDelay = options.reconnectionDelay ?? 1e3;
+	const reconnectionDelayMax = options.reconnectionDelayMax ?? 5e3;
+	const timeout = options.timeout ?? 2e4;
+	const emitter = new TransportEmitter();
+	const sockets = /* @__PURE__ */ new Map();
+	let manager = null;
+	let currentTarget = null;
+	let status = { up: false };
+	let disposed = false;
+	function buildAuth(target) {
+		const auth = { token: `Bearer ${target.tokens.access}` };
+		if (target.tokens.proxySession) auth.session = target.tokens.proxySession;
+		return auth;
+	}
+	function buildQuery(target) {
+		const q = {};
+		if (target.tokens.proxySession) q.session = target.tokens.proxySession;
+		return q;
+	}
+	function markUp() {
+		if (status.up) return;
+		status = { up: true };
+		emitter.emit("up", void 0);
+	}
+	function markDown(reason) {
+		if (!status.up && status.lastError === reason) return;
+		status = {
+			up: false,
+			lastError: reason
+		};
+		emitter.emit("down", { reason });
+	}
+	function bindMainSocketEvents(socket) {
+		socket.on("connect", () => markUp());
+		socket.on("disconnect", (reason) => markDown(reason));
+		socket.on("connect_error", (err) => {
+			const msg = err?.message ?? "connect_error";
+			if (msg.toLowerCase().includes("auth") || msg.toLowerCase().includes("unauthorized")) {
+				emitter.emit("auth-error", { message: msg });
+				return;
+			}
+			markDown(msg);
+		});
+	}
+	function openSocket(namespace, target) {
+		const sock = io(`${target.endpoint.url}${namespace}`, {
+			path,
+			auth: buildAuth(target),
+			query: buildQuery(target),
+			reconnection,
+			reconnectionDelay,
+			reconnectionDelayMax,
+			timeout,
+			rejectUnauthorized: false,
+			transports: ["websocket"]
+		});
+		sockets.set(namespace, sock);
+		return sock;
+	}
+	function rebuildManager(target) {
+		closeAllSockets();
+		manager = new Manager(target.endpoint.url, {
+			path,
+			autoConnect: false,
+			reconnection,
+			reconnectionDelay,
+			reconnectionDelayMax,
+			timeout,
+			rejectUnauthorized: false,
+			transports: ["websocket"]
+		});
+		bindMainSocketEvents(openSocket(mainNs, target));
+	}
+	function closeAllSockets() {
+		for (const sock of sockets.values()) {
+			sock.removeAllListeners();
+			sock.disconnect();
+		}
+		sockets.clear();
+		if (manager) {
+			manager._close();
+			manager = null;
+		}
+	}
+	function rebindAuth(target) {
+		const auth = buildAuth(target);
+		for (const sock of sockets.values()) sock.auth = auth;
+	}
+	async function apply(target) {
+		if (disposed) throw new Error("socketio-transport disposed");
+		if (isSameTarget(currentTarget, target)) return;
+		const endpointChanged = isEndpointChange(currentTarget, target);
+		currentTarget = target;
+		if (!target) {
+			closeAllSockets();
+			markDown("detached");
+			return;
+		}
+		if (endpointChanged || !manager) {
+			rebuildManager(target);
+			return;
+		}
+		rebindAuth(target);
+	}
+	function health() {
+		return status;
+	}
+	function on(event, handler) {
+		return emitter.on(event, handler);
+	}
+	async function dispose() {
+		disposed = true;
+		closeAllSockets();
+		currentTarget = null;
+		status = { up: false };
+		emitter.clear();
+	}
+	function socket(namespace = mainNs) {
+		return sockets.get(namespace) ?? null;
+	}
+	function ensureSocket(namespace) {
+		if (!currentTarget) return null;
+		let sock = sockets.get(namespace);
+		if (!sock) sock = openSocket(namespace, currentTarget);
+		return sock;
+	}
+	return {
+		get spec() {
+			return spec;
+		},
+		get manager() {
+			return manager;
+		},
+		apply,
+		health,
+		on,
+		dispose,
+		socket,
+		ensureSocket
+	};
+}
+//#endregion
+export { createSocketioTransport };

package/dist/transports/ws.d.ts

@@ -0,0 +1,34 @@
+import { TransportSpec } from '../core/types.js';
+import { PerResourceTransport, Unsubscribe } from './contract.js';
+export interface WsHandleSpec {
+    readonly path: string;
+    readonly query?: Record<string, string>;
+    readonly protocols?: string | readonly string[];
+    readonly binaryType?: 'arraybuffer' | 'blob';
+}
+export type WsEvent = 'open' | 'close' | 'message' | 'error';
+export interface WsCloseInfo {
+    readonly code: number;
+    readonly reason: string;
+    readonly wasClean: boolean;
+}
+export type WsEventPayload<E extends WsEvent> = E extends 'open' ? void : E extends 'close' ? WsCloseInfo : E extends 'message' ? MessageEvent : E extends 'error' ? Event : never;
+export type WsEventHandler<E extends WsEvent> = (payload: WsEventPayload<E>) => void;
+export interface WsHandle {
+    readonly readyState: number;
+    readonly url: string | null;
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    close(code?: number, reason?: string): void;
+    on<E extends WsEvent>(event: E, handler: WsEventHandler<E>): Unsubscribe;
+    dispose(): void;
+}
+export interface WsTransportOptions {
+    readonly spec?: Partial<TransportSpec>;
+    readonly webSocketCtor?: typeof WebSocket;
+    readonly tokenParam?: string;
+    readonly sessionParam?: string;
+}
+export interface WsTransport extends PerResourceTransport<WsHandle, WsHandleSpec> {
+    readonly handleCount: number;
+}
+export declare function createWsTransport(options?: WsTransportOptions): WsTransport;

package/dist/transports/ws.js

@@ -0,0 +1,228 @@
+import { n as isEndpointChange, r as isSameTarget, t as TransportEmitter } from "../contract-d-0gfY8v.js";
+//#region src/transports/ws.ts
+var WS_SPEC = {
+	id: "ws",
+	kind: "per-resource",
+	phaseGating: false
+};
+var WS_CLOSE_TARGET_CHANGED = 4e3;
+var WS_CLOSE_DETACHED = 4001;
+var WS_CLOSE_DISPOSED = 4002;
+function createWsTransport(options = {}) {
+	const spec = {
+		...WS_SPEC,
+		...options.spec
+	};
+	const tokenParam = options.tokenParam ?? "token";
+	const sessionParam = options.sessionParam ?? "session";
+	const WsCtor = options.webSocketCtor ?? (typeof WebSocket !== "undefined" ? WebSocket : void 0);
+	const emitter = new TransportEmitter();
+	const handles = /* @__PURE__ */ new Set();
+	let currentTarget = null;
+	let status = { up: false };
+	let disposed = false;
+	function ensureCtor() {
+		if (!WsCtor) throw new Error("ws-transport: no WebSocket constructor available; pass webSocketCtor in non-browser environments");
+		return WsCtor;
+	}
+	function buildUrl(target, handleSpec) {
+		const base = new URL(target.endpoint.url);
+		const wsProtocol = base.protocol === "https:" ? "wss:" : "ws:";
+		const port = base.port || (base.protocol === "https:" ? "443" : "80");
+		const params = new URLSearchParams();
+		for (const [k, v] of Object.entries(handleSpec.query ?? {})) if (v !== void 0 && v !== null && v !== "") params.set(k, v);
+		params.set(tokenParam, target.tokens.access);
+		if (target.tokens.proxySession) params.set(sessionParam, target.tokens.proxySession);
+		return `${wsProtocol}//${base.hostname}:${port}${handleSpec.path}?${params.toString()}`;
+	}
+	function isAuthCloseEvent(event) {
+		if (event.code === 1008 || event.code === 4401) return true;
+		if (!event.reason) return false;
+		const lower = event.reason.toLowerCase();
+		return lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("401") || lower.includes("403");
+	}
+	function bindWs(handle, ws) {
+		ws.onopen = () => {
+			if (handle.disposed || handle.ws !== ws) return;
+			if (!status.up) {
+				status = { up: true };
+				emitter.emit("up", void 0);
+			}
+			for (const fn of [...handle.listeners.open]) fn();
+		};
+		ws.onclose = (event) => {
+			if (handle.ws === ws) {
+				handle.ws = null;
+				handle.url = null;
+			}
+			if (isAuthCloseEvent(event)) emitter.emit("auth-error", { message: event.reason || `ws close code ${event.code}` });
+			const info = {
+				code: event.code,
+				reason: event.reason,
+				wasClean: event.wasClean
+			};
+			for (const fn of [...handle.listeners.close]) fn(info);
+		};
+		ws.onmessage = (event) => {
+			if (handle.disposed || handle.ws !== ws) return;
+			for (const fn of [...handle.listeners.message]) fn(event);
+		};
+		ws.onerror = (event) => {
+			if (handle.disposed || handle.ws !== ws) return;
+			for (const fn of [...handle.listeners.error]) fn(event);
+		};
+	}
+	function closeWs(handle, code, reason) {
+		const ws = handle.ws;
+		if (!ws) return;
+		const Ctor = ensureCtor();
+		if (ws.readyState === Ctor.OPEN || ws.readyState === Ctor.CONNECTING) {
+			try {
+				ws.close(code, reason);
+			} catch {}
+			return;
+		}
+		if (handle.ws === ws) {
+			handle.ws = null;
+			handle.url = null;
+		}
+		const info = {
+			code,
+			reason,
+			wasClean: false
+		};
+		for (const fn of [...handle.listeners.close]) fn(info);
+	}
+	function openWs(handle) {
+		if (handle.disposed) return;
+		if (!currentTarget) return;
+		const url = buildUrl(currentTarget, handle.spec);
+		const ws = new (ensureCtor())(url, handle.spec.protocols);
+		if (handle.spec.binaryType) ws.binaryType = handle.spec.binaryType;
+		handle.ws = ws;
+		handle.url = url;
+		bindWs(handle, ws);
+	}
+	function recycleAll(code, reason) {
+		const snapshot = [...handles];
+		for (const handle of snapshot) closeWs(handle, code, reason);
+		if (status.up) {
+			status = {
+				up: false,
+				lastError: reason
+			};
+			emitter.emit("down", { reason });
+		}
+		if (!currentTarget) return;
+		for (const handle of handles) if (!handle.disposed) openWs(handle);
+	}
+	async function apply(target) {
+		if (disposed) throw new Error("ws-transport disposed");
+		if (isSameTarget(currentTarget, target)) return;
+		const endpointChanged = isEndpointChange(currentTarget, target);
+		currentTarget = target;
+		if (!target) {
+			const snapshot = [...handles];
+			for (const handle of snapshot) closeWs(handle, WS_CLOSE_DETACHED, "detached");
+			status = { up: false };
+			emitter.emit("down", { reason: "detached" });
+			return;
+		}
+		if (endpointChanged) recycleAll(WS_CLOSE_TARGET_CHANGED, "endpoint-changed");
+	}
+	function health() {
+		return status;
+	}
+	function on(event, handler) {
+		return emitter.on(event, handler);
+	}
+	async function dispose() {
+		disposed = true;
+		const snapshot = [...handles];
+		for (const handle of snapshot) {
+			handle.disposed = true;
+			handle.listeners.open.clear();
+			handle.listeners.close.clear();
+			handle.listeners.message.clear();
+			handle.listeners.error.clear();
+			closeWs(handle, WS_CLOSE_DISPOSED, "disposed");
+		}
+		handles.clear();
+		currentTarget = null;
+		status = { up: false };
+		emitter.clear();
+	}
+	function open(handleSpec) {
+		if (disposed) throw new Error("ws-transport disposed");
+		const handle = {
+			api: void 0,
+			spec: handleSpec,
+			listeners: {
+				open: /* @__PURE__ */ new Set(),
+				close: /* @__PURE__ */ new Set(),
+				message: /* @__PURE__ */ new Set(),
+				error: /* @__PURE__ */ new Set()
+			},
+			ws: null,
+			url: null,
+			disposed: false
+		};
+		function send(data) {
+			if (handle.disposed) throw new Error("ws-handle disposed");
+			const ws = handle.ws;
+			if (!ws) throw new Error("ws-handle: no active socket");
+			if (ws.readyState !== WsCtor.OPEN) throw new Error("ws-handle: socket not open");
+			ws.send(data);
+		}
+		function close(code, reason) {
+			closeWs(handle, code ?? 1e3, reason ?? "");
+		}
+		function onHandle(event, handler) {
+			const set = handle.listeners[event];
+			set.add(handler);
+			return () => {
+				set.delete(handler);
+			};
+		}
+		function disposeHandle() {
+			if (handle.disposed) return;
+			handle.disposed = true;
+			handle.listeners.open.clear();
+			handle.listeners.close.clear();
+			handle.listeners.message.clear();
+			handle.listeners.error.clear();
+			closeWs(handle, WS_CLOSE_DISPOSED, "disposed");
+			handles.delete(handle);
+		}
+		handle.api = {
+			get readyState() {
+				return handle.ws?.readyState ?? WsCtor?.CLOSED ?? 3;
+			},
+			get url() {
+				return handle.url;
+			},
+			send,
+			close,
+			on: onHandle,
+			dispose: disposeHandle
+		};
+		handles.add(handle);
+		if (currentTarget) openWs(handle);
+		return handle.api;
+	}
+	return {
+		get spec() {
+			return spec;
+		},
+		get handleCount() {
+			return handles.size;
+		},
+		apply,
+		health,
+		on,
+		dispose,
+		open
+	};
+}
+//#endregion
+export { createWsTransport };

package/dist/worker/index.d.ts

@@ -0,0 +1,3 @@
+export { createWorkerKernelMirror } from './mirror.js';
+export type { MirrorListener, Unsubscribe, WorkerKernelMirror, WorkerKernelMirrorOptions } from './mirror.js';
+export type { KernelSyncMessage, KernelSyncRequestMessage, MessageSource, WorkerHost, WorkerMessage } from './protocol.js';

package/dist/worker/mirror.d.ts

@@ -0,0 +1,17 @@
+import { ConnectionPhase, ConnectionTarget } from '../core/types.js';
+import { MessageSource } from './protocol.js';
+export type Unsubscribe = () => void;
+export type MirrorListener = (next: ConnectionPhase, prev: ConnectionPhase) => void;
+export interface WorkerKernelMirror {
+    readonly phase: ConnectionPhase;
+    readonly target: ConnectionTarget | null;
+    subscribe(listener: MirrorListener): Unsubscribe;
+    onRevalidate(listener: () => void): Unsubscribe;
+    requestSync(): void;
+    dispose(): void;
+}
+export interface WorkerKernelMirrorOptions {
+    readonly source: MessageSource;
+    readonly initial?: ConnectionPhase;
+}
+export declare function createWorkerKernelMirror(options: WorkerKernelMirrorOptions): WorkerKernelMirror;

package/dist/worker/protocol.d.ts

@@ -0,0 +1,23 @@
+import { ConnectionPhase } from '../core/types.js';
+export interface KernelSyncMessage {
+    readonly type: 'kernel-sync';
+    readonly generation: number;
+    readonly phase: ConnectionPhase;
+}
+export interface KernelSyncRequestMessage {
+    readonly type: 'kernel-sync-request';
+}
+export interface KernelRevalidateMessage {
+    readonly type: 'kernel-revalidate';
+}
+export type WorkerMessage = KernelSyncMessage | KernelSyncRequestMessage | KernelRevalidateMessage;
+export interface MessageSource {
+    postMessage(message: WorkerMessage): void;
+    addEventListener(type: 'message', listener: (event: MessageEvent<WorkerMessage>) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent<WorkerMessage>) => void): void;
+}
+export interface WorkerHost {
+    postMessage(message: WorkerMessage): void;
+    addEventListener?(type: 'message', listener: (event: MessageEvent<WorkerMessage>) => void): void;
+    removeEventListener?(type: 'message', listener: (event: MessageEvent<WorkerMessage>) => void): void;
+}

package/dist/worker.js

@@ -0,0 +1,66 @@
+//#region src/worker/mirror.ts
+function createWorkerKernelMirror(options) {
+	let current = options.initial ?? { kind: "idle" };
+	let lastGeneration = -1;
+	const listeners = /* @__PURE__ */ new Set();
+	const revalidateListeners = /* @__PURE__ */ new Set();
+	let disposed = false;
+	function handler(event) {
+		if (disposed) return;
+		const msg = event.data;
+		if (!msg) return;
+		if (msg.type === "kernel-revalidate") {
+			for (const l of [...revalidateListeners]) try {
+				l();
+			} catch {}
+			return;
+		}
+		if (msg.type !== "kernel-sync") return;
+		if (msg.generation <= lastGeneration) return;
+		lastGeneration = msg.generation;
+		const prev = current;
+		current = msg.phase;
+		if (prev === current) return;
+		for (const l of [...listeners]) try {
+			l(current, prev);
+		} catch {}
+	}
+	options.source.addEventListener("message", handler);
+	function targetOf(p) {
+		if (p.kind === "online") return p.target;
+		if (p.kind === "reconnecting") return p.lastTarget;
+		return null;
+	}
+	return {
+		get phase() {
+			return current;
+		},
+		get target() {
+			return targetOf(current);
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		onRevalidate(listener) {
+			revalidateListeners.add(listener);
+			return () => {
+				revalidateListeners.delete(listener);
+			};
+		},
+		requestSync() {
+			if (disposed) return;
+			options.source.postMessage({ type: "kernel-sync-request" });
+		},
+		dispose() {
+			disposed = true;
+			options.source.removeEventListener("message", handler);
+			listeners.clear();
+			revalidateListeners.clear();
+		}
+	};
+}
+//#endregion
+export { createWorkerKernelMirror };

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@camera.ui/transport",
+  "version": "0.0.1",
+  "description": "camera.ui transport layer — framework-agnostic connection kernel, reducer state, pluggable transports (HTTP/WS/Socket.IO/NATS), lifecycle effects and worker bridge",
+  "author": "seydx (https://github.com/cameraui/clients)",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./transports/http": {
+      "types": "./dist/transports/http.d.ts",
+      "import": "./dist/transports/http.js"
+    },
+    "./transports/socketio": {
+      "types": "./dist/transports/socketio.d.ts",
+      "import": "./dist/transports/socketio.js"
+    },
+    "./transports/nats": {
+      "types": "./dist/transports/nats.d.ts",
+      "import": "./dist/transports/nats.js"
+    },
+    "./transports/ws": {
+      "types": "./dist/transports/ws.d.ts",
+      "import": "./dist/transports/ws.js"
+    },
+    "./transports/nativeHttp": {
+      "types": "./dist/transports/nativeHttp.d.ts",
+      "import": "./dist/transports/nativeHttp.js"
+    },
+    "./worker": {
+      "types": "./dist/worker/index.d.ts",
+      "import": "./dist/worker.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "scripts": {
+    "build": "rimraf dist && vite build",
+    "format": "prettier --write 'src/' --ignore-unknown --no-error-on-unmatched-pattern",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .",
+    "install-updates": "npm i --save",
+    "prepublishOnly": "npm i --package-lock-only && npm run lint:fix && npm run format && npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "update": "updates --update ./"
+  },
+  "dependencies": {
+    "@camera.ui/rpc": "file:../../externals/rpc/node",
+    "axios": "^1.18.0",
+    "socket.io-client": "^4.8.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.4",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@typescript-eslint/parser": "^8.61.1",
+    "@vue/language-core": "^3.1.8",
+    "eslint": "9.39.2",
+    "globals": "^17.6.0",
+    "jiti": "^2.7.0",
+    "prettier": "^3.8.4",
+    "rimraf": "^6.1.3",
+    "typescript": "5.9.3",
+    "typescript-eslint": "^8.61.1",
+    "unplugin-dts": "^1.0.2",
+    "updates": "^17.18.0",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  },
+  "bugs": {
+    "url": "https://github.com/cameraui/clients/issues"
+  },
+  "homepage": "https://github.com/cameraui/clients/tree/main/packages/transport#readme",
+  "keywords": [
+    "camera.ui",
+    "transport",
+    "connection"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cameraui/clients.git",
+    "directory": "packages/transport"
+  }
+}