@lemoncloud/chatic-sockets-lib 0.1.0

package/dist/client-socket-v2/socket-runtime.js

@@ -0,0 +1,52 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketRuntime = void 0;
+const reconnect_controller_1 = require("./reconnect-controller");
+const connection_rotation_controller_1 = require("./connection-rotation-controller");
+const keep_alive_loop_1 = require("./keep-alive-loop");
+const shared_timer_scheduler_1 = require("./shared-timer-scheduler");
+const sync_scheduler_1 = require("./sync-scheduler");
+class SocketRuntime {
+    constructor(options) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        this.options = options;
+        this.start = () => __awaiter(this, void 0, void 0, function* () {
+            this.keepAlive.start();
+            this.rotation.start();
+            yield this.reconnect.start();
+        });
+        this.stop = () => __awaiter(this, void 0, void 0, function* () {
+            this.rotation.stop();
+            this.keepAlive.stop();
+            yield this.reconnect.stop();
+        });
+        this.startSync = (target) => this.scheduler.start(target);
+        this.stopSync = (target) => this.scheduler.stop(target);
+        this.stopAllSync = () => this.scheduler.stopAll();
+        this.listSyncTargets = () => this.scheduler.list();
+        this.updateLocalSnapshot = (target, snapshot) => this.scheduler.updateLocalSnapshot(target, snapshot);
+        this.timerScheduler = (_b = (_a = options.timerScheduler) !== null && _a !== void 0 ? _a : options.client.timerScheduler) !== null && _b !== void 0 ? _b : new shared_timer_scheduler_1.InMemorySharedTimerScheduler();
+        this.scheduler =
+            (_c = options.scheduler) !== null && _c !== void 0 ? _c : new sync_scheduler_1.DomainSyncScheduler({
+                client: options.client,
+                plans: (_d = options.syncPlans) !== null && _d !== void 0 ? _d : [],
+                timerScheduler: this.timerScheduler,
+            });
+        this.keepAlive =
+            (_e = options.keepAlive) !== null && _e !== void 0 ? _e : new keep_alive_loop_1.KeepAliveLoop(Object.assign({ client: options.client, timerScheduler: this.timerScheduler }, (options.keepAliveOptions || {})));
+        this.reconnect =
+            (_f = options.reconnect) !== null && _f !== void 0 ? _f : new reconnect_controller_1.AutoReconnectController(Object.assign({ client: options.client, timerScheduler: this.timerScheduler }, (options.reconnectOptions || {})));
+        this.rotation =
+            (_g = options.rotation) !== null && _g !== void 0 ? _g : new connection_rotation_controller_1.ConnectionRotationController(Object.assign({ client: options.client, reconnect: this.reconnect, timerScheduler: this.timerScheduler }, (options.rotationOptions || {})));
+    }
+}
+exports.SocketRuntime = SocketRuntime;

package/dist/client-socket-v2/socket-transport.d.ts

@@ -0,0 +1,18 @@
+import type { ClientSocketState, SocketFactoryContext, SocketLike, SocketTransport, SocketTransportEventMap } from './types';
+export declare class WebSocketTransport implements SocketTransport {
+    readonly url: string;
+    readonly protocols?: string | string[];
+    private readonly socketFactory;
+    private _state;
+    private socket?;
+    private unbinders;
+    private readonly listeners;
+    constructor(url: string, protocols?: string | string[], socketFactory?: (context: SocketFactoryContext) => SocketLike);
+    get state(): ClientSocketState;
+    on: <TType extends keyof SocketTransportEventMap>(type: TType, listener: (event: SocketTransportEventMap[TType]) => void) => (() => void);
+    connect: () => Promise<void>;
+    disconnect: (code?: number, reason?: string) => Promise<void>;
+    send: (raw: string) => void;
+    private emit;
+    private cleanupSocket;
+}

package/dist/client-socket-v2/socket-transport.js

@@ -0,0 +1,124 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSocketTransport = void 0;
+const common_1 = require("./common");
+const OPEN_STATE = 1;
+const bindSocketListener = (socket, type, listener) => {
+    if (socket.addEventListener) {
+        socket.addEventListener(type, listener);
+        return () => { var _a; return (_a = socket.removeEventListener) === null || _a === void 0 ? void 0 : _a.call(socket, type, listener); };
+    }
+    const key = `on${type}`;
+    const prev = socket[key];
+    socket[key] = listener;
+    return () => {
+        if (socket[key] === listener)
+            socket[key] = prev !== null && prev !== void 0 ? prev : null;
+    };
+};
+class WebSocketTransport {
+    constructor(url, protocols, socketFactory = context => new globalThis.WebSocket(context.url, context.protocols)) {
+        this.url = url;
+        this.protocols = protocols;
+        this.socketFactory = socketFactory;
+        this._state = 'idle';
+        this.unbinders = [];
+        this.listeners = new Map();
+        this.on = (type, listener) => {
+            var _a;
+            const bucket = (_a = this.listeners.get(type)) !== null && _a !== void 0 ? _a : new Set();
+            bucket.add(listener);
+            this.listeners.set(type, bucket);
+            return () => {
+                bucket.delete(listener);
+                if (!bucket.size)
+                    this.listeners.delete(type);
+            };
+        };
+        this.connect = () => __awaiter(this, void 0, void 0, function* () {
+            if (this._state === 'connected')
+                return;
+            if (this._state === 'connecting')
+                return;
+            this.cleanupSocket();
+            this._state = 'connecting';
+            const socket = this.socketFactory({ url: this.url, protocols: this.protocols });
+            this.socket = socket;
+            yield new Promise((resolve, reject) => {
+                let connectSettled = false;
+                const settleConnect = (handler) => {
+                    if (connectSettled)
+                        return;
+                    connectSettled = true;
+                    handler();
+                };
+                this.unbinders = [
+                    bindSocketListener(socket, 'open', () => {
+                        this._state = 'connected';
+                        this.emit('open', undefined);
+                        settleConnect(() => resolve());
+                    }),
+                    bindSocketListener(socket, 'close', event => {
+                        this._state = 'closed';
+                        this.emit('close', {
+                            code: event === null || event === void 0 ? void 0 : event.code,
+                            reason: event === null || event === void 0 ? void 0 : event.reason,
+                            wasClean: event === null || event === void 0 ? void 0 : event.wasClean,
+                        });
+                        settleConnect(() => resolve());
+                    }),
+                    bindSocketListener(socket, 'error', event => {
+                        var _a;
+                        const error = (_a = event === null || event === void 0 ? void 0 : event.error) !== null && _a !== void 0 ? _a : new Error(`socket transport error`);
+                        this.emit('error', { error });
+                        if (this._state !== 'connected')
+                            this._state = 'closed';
+                        settleConnect(() => reject(error));
+                    }),
+                    bindSocketListener(socket, 'message', event => {
+                        this.emit('message', { data: (0, common_1.asString)(event === null || event === void 0 ? void 0 : event.data, '') });
+                    }),
+                ];
+            });
+        });
+        this.disconnect = (code, reason) => __awaiter(this, void 0, void 0, function* () {
+            if (!this.socket) {
+                this._state = 'closed';
+                return;
+            }
+            this._state = 'closing';
+            const socket = this.socket;
+            socket.close(code, reason);
+            this.cleanupSocket();
+            this._state = 'closed';
+            this.emit('close', { code, reason, wasClean: true });
+        });
+        this.send = (raw) => {
+            if (!this.socket || this.socket.readyState !== undefined && this.socket.readyState !== OPEN_STATE) {
+                throw new Error(`503 SOCKET NOT CONNECTED - WebSocketTransport.send()`);
+            }
+            this.socket.send(raw);
+        };
+        this.emit = (type, event) => {
+            var _a;
+            (_a = this.listeners.get(type)) === null || _a === void 0 ? void 0 : _a.forEach(listener => listener(event));
+        };
+        this.cleanupSocket = () => {
+            this.unbinders.splice(0).forEach(unbind => unbind());
+            this.socket = undefined;
+        };
+    }
+    get state() {
+        return this._state;
+    }
+}
+exports.WebSocketTransport = WebSocketTransport;

package/dist/client-socket-v2/sync-scheduler.d.ts

@@ -0,0 +1,36 @@
+import type { ClientSocketV2, DomainSyncPlan, SharedTimerScheduler, SyncScheduler, SyncTargetDescriptor } from './types';
+export interface SyncSchedulerOptions {
+    client: ClientSocketV2;
+    plans: DomainSyncPlan<any>[];
+    now?: () => number;
+    timerScheduler?: SharedTimerScheduler;
+    timerPrefix?: string;
+}
+export declare class DomainSyncScheduler implements SyncScheduler {
+    private readonly options;
+    private readonly plans;
+    private readonly targets;
+    private readonly snapshots;
+    private readonly now;
+    private readonly timerScheduler?;
+    private readonly timerPrefix;
+    private readonly unsubs;
+    constructor(options: SyncSchedulerOptions);
+    start: (target: SyncTargetDescriptor) => void;
+    stop: (target: SyncTargetDescriptor) => void;
+    stopAll: () => void;
+    list: () => SyncTargetDescriptor[];
+    updateLocalSnapshot: (target: SyncTargetDescriptor, snapshot: unknown) => void;
+    destroy: () => void;
+    private resolvePlan;
+    private findEntry;
+    private buildContext;
+    private handleConnected;
+    private stopAllTimers;
+    private clearTimer;
+    private scheduleNow;
+    private scheduleNext;
+    private toTimerKey;
+    private runEntry;
+    private handleTrigger;
+}

package/dist/client-socket-v2/sync-scheduler.js

@@ -0,0 +1,189 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DomainSyncScheduler = void 0;
+class DomainSyncScheduler {
+    constructor(options) {
+        var _a, _b;
+        this.options = options;
+        this.targets = new Map();
+        this.snapshots = new Map();
+        this.unsubs = [];
+        this.start = (target) => {
+            const plan = this.resolvePlan(target);
+            const key = plan.getKey(target);
+            const entry = this.targets.get(key);
+            if (entry) {
+                entry.target = Object.assign(Object.assign({}, entry.target), target);
+                return;
+            }
+            this.targets.set(key, { target, plan });
+            if (this.options.client.state === 'connected')
+                this.scheduleNow(key);
+        };
+        this.stop = (target) => {
+            const entry = this.findEntry(target);
+            if (!entry)
+                return;
+            this.clearTimer(entry);
+            this.targets.delete(entry.plan.getKey(entry.target));
+            this.snapshots.delete(entry.plan.getKey(entry.target));
+        };
+        this.stopAll = () => {
+            this.stopAllTimers();
+            this.targets.clear();
+            this.snapshots.clear();
+        };
+        this.list = () => [...this.targets.values()].map(entry => (Object.assign({}, entry.target)));
+        this.updateLocalSnapshot = (target, snapshot) => {
+            var _a, _b, _c;
+            const entry = (_a = this.findEntry(target)) !== null && _a !== void 0 ? _a : (() => {
+                const plan = this.resolvePlan(target);
+                const key = plan.getKey(target);
+                return { target, plan, key };
+            })();
+            const key = 'key' in entry ? entry.key : entry.plan.getKey(entry.target);
+            this.snapshots.set(key, snapshot);
+            (_c = (_b = entry.plan).updateLocalState) === null || _c === void 0 ? void 0 : _c.call(_b, entry.target, snapshot, this.buildContext());
+        };
+        this.destroy = () => {
+            this.stopAllTimers();
+            this.unsubs.splice(0).forEach(unsub => unsub());
+        };
+        this.resolvePlan = (target) => {
+            var _a;
+            const plan = this.plans.find(candidate => candidate.supports(target));
+            if (!plan)
+                throw new Error(`404 NOT FOUND - sync plan[${(_a = target === null || target === void 0 ? void 0 : target.type) !== null && _a !== void 0 ? _a : '-'}]`);
+            return plan;
+        };
+        this.findEntry = (target) => {
+            for (const entry of this.targets.values()) {
+                if (!entry.plan.supports(target))
+                    continue;
+                if (entry.plan.getKey(entry.target) === entry.plan.getKey(target))
+                    return entry;
+            }
+            return undefined;
+        };
+        this.buildContext = () => ({
+            client: this.options.client,
+            now: this.now,
+            readSnapshot: target => {
+                const plan = this.resolvePlan(target);
+                return this.snapshots.get(plan.getKey(target));
+            },
+            writeSnapshot: (target, snapshot) => {
+                const plan = this.resolvePlan(target);
+                const key = plan.getKey(target);
+                if (snapshot === undefined) {
+                    this.snapshots.delete(key);
+                    return;
+                }
+                this.snapshots.set(key, snapshot);
+            },
+            requestResync: (target) => __awaiter(this, void 0, void 0, function* () {
+                const entry = this.findEntry(target);
+                const key = entry ? entry.plan.getKey(entry.target) : this.resolvePlan(target).getKey(target);
+                yield this.runEntry(key);
+            }),
+        });
+        this.handleConnected = () => __awaiter(this, void 0, void 0, function* () {
+            var _c, _d;
+            const ctx = this.buildContext();
+            for (const [key, entry] of this.targets.entries()) {
+                yield ((_d = (_c = entry.plan).onConnected) === null || _d === void 0 ? void 0 : _d.call(_c, entry.target, ctx));
+                this.scheduleNow(key);
+            }
+        });
+        this.stopAllTimers = () => {
+            this.targets.forEach(entry => this.clearTimer(entry));
+        };
+        this.clearTimer = (entry) => {
+            var _a;
+            (_a = this.timerScheduler) === null || _a === void 0 ? void 0 : _a.cancel(this.toTimerKey(entry.plan.getKey(entry.target)));
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            entry.timer = undefined;
+        };
+        this.scheduleNow = (key) => {
+            const entry = this.targets.get(key);
+            if (!entry)
+                return;
+            this.clearTimer(entry);
+            if (this.timerScheduler) {
+                this.timerScheduler.schedule(this.toTimerKey(key), 0, () => this.runEntry(key));
+                return;
+            }
+            entry.timer = setTimeout(() => void this.runEntry(key), 0);
+        };
+        this.scheduleNext = (key) => {
+            var _a, _b, _c, _d;
+            const entry = this.targets.get(key);
+            if (!entry)
+                return;
+            this.clearTimer(entry);
+            if (this.options.client.state !== 'connected')
+                return;
+            const intervalMs = (_d = (_a = entry.target.intervalMs) !== null && _a !== void 0 ? _a : (_c = (_b = entry.plan).getIntervalMs) === null || _c === void 0 ? void 0 : _c.call(_b, entry.target)) !== null && _d !== void 0 ? _d : 5000;
+            if (this.timerScheduler) {
+                this.timerScheduler.schedule(this.toTimerKey(key), intervalMs, () => this.runEntry(key));
+                return;
+            }
+            entry.timer = setTimeout(() => void this.runEntry(key), intervalMs);
+        };
+        this.toTimerKey = (key) => `${this.timerPrefix}${key}`;
+        this.runEntry = (key) => __awaiter(this, void 0, void 0, function* () {
+            const entry = this.targets.get(key);
+            if (!entry || this.options.client.state !== 'connected')
+                return;
+            if (entry.inFlight)
+                return;
+            const ctx = this.buildContext();
+            entry.inFlight = Promise.resolve(entry.plan.run(entry.target, ctx))
+                .catch(() => undefined)
+                .then(() => {
+                entry.inFlight = undefined;
+                this.scheduleNext(key);
+            });
+            yield entry.inFlight;
+        });
+        this.handleTrigger = (message) => __awaiter(this, void 0, void 0, function* () {
+            var _e;
+            const type = `${(_e = message === null || message === void 0 ? void 0 : message.type) !== null && _e !== void 0 ? _e : ''}`;
+            if (!type.endsWith('.sync'))
+                return;
+            const targets = [...this.targets.values()];
+            const ctx = this.buildContext();
+            yield Promise.all(targets.map((entry) => __awaiter(this, void 0, void 0, function* () {
+                if (!entry.plan.onTrigger)
+                    return;
+                if (!type.startsWith(`${entry.target.type}.`))
+                    return;
+                yield entry.plan.onTrigger(entry.target, message, ctx);
+            })));
+        });
+        this.plans = [...(options.plans || [])];
+        this.now = (_a = options.now) !== null && _a !== void 0 ? _a : (() => Date.now());
+        this.timerScheduler = options.timerScheduler;
+        this.timerPrefix = (_b = options.timerPrefix) !== null && _b !== void 0 ? _b : 'sync:';
+        this.unsubs.push(options.client.onState(event => {
+            if (event.next === 'connected')
+                void this.handleConnected();
+            if (event.next === 'closing' || event.next === 'closed')
+                this.stopAllTimers();
+        }));
+        this.unsubs.push(options.client.onMessage(({ message }) => {
+            void this.handleTrigger(message);
+        }));
+    }
+}
+exports.DomainSyncScheduler = DomainSyncScheduler;

package/dist/client-socket-v2/types.d.ts

@@ -0,0 +1,135 @@
+import type { ResolveSocketPacketType, SocketMessage, SocketPacketInputType, SocketPacketRequestData, SocketPacketResponseData, SocketPacketType } from '../lib/types';
+import type { DeviceBootstrapInput } from '../lib/device/types';
+export declare type ClientSocketState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
+export interface SocketLike {
+    readonly readyState?: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event?: any) => void): void;
+    removeEventListener?(type: 'open' | 'close' | 'error' | 'message', listener: (event?: any) => void): void;
+    onopen?: ((event?: any) => void) | null;
+    onclose?: ((event?: any) => void) | null;
+    onerror?: ((event?: any) => void) | null;
+    onmessage?: ((event?: any) => void) | null;
+}
+export interface SocketFactoryContext {
+    url: string;
+    protocols?: string | string[];
+}
+export interface SocketTransportEventMap {
+    open: void;
+    close: {
+        code?: number;
+        reason?: string;
+        wasClean?: boolean;
+    };
+    error: {
+        error?: unknown;
+    };
+    message: {
+        data: string;
+    };
+}
+export interface SocketTransport {
+    readonly url: string;
+    readonly protocols?: string | string[];
+    readonly state: ClientSocketState;
+    connect(): Promise<void>;
+    disconnect(code?: number, reason?: string): Promise<void>;
+    send(raw: string): void;
+    on<TType extends keyof SocketTransportEventMap>(type: TType, listener: (event: SocketTransportEventMap[TType]) => void): () => void;
+}
+export interface ClientSocketOptions {
+    url: string;
+    protocols?: string | string[];
+    device?: DeviceBootstrapInput | null;
+    socketFactory?: (context: SocketFactoryContext) => SocketLike;
+    aliases?: Partial<Record<SocketPacketInputType | string, SocketPacketType>>;
+    timerScheduler?: SharedTimerScheduler;
+    requestTimeoutMs?: number;
+    createMid?: () => string;
+    now?: () => number;
+}
+export interface ClientSocketStateEvent {
+    prev: ClientSocketState;
+    next: ClientSocketState;
+}
+export interface ClientSocketErrorEvent {
+    error: unknown;
+    phase: 'connect' | 'disconnect' | 'message' | 'request' | 'transport';
+    raw?: unknown;
+}
+export interface ClientSocketMessageEvent<T = any> {
+    message: SocketMessage<T>;
+    raw: string;
+}
+export interface ClientSocketV2 {
+    readonly state: ClientSocketState;
+    readonly deviceDefaults?: DeviceBootstrapInput;
+    readonly timerScheduler?: SharedTimerScheduler;
+    connect(): Promise<void>;
+    disconnect(code?: number, reason?: string): Promise<void>;
+    send<TType extends SocketPacketInputType>(type: TType, data?: SocketPacketRequestData<ResolveSocketPacketType<TType>>): void;
+    send<T = any>(message: SocketMessage<T>): void;
+    request<TType extends SocketPacketInputType>(type: TType, data?: SocketPacketRequestData<ResolveSocketPacketType<TType>>, options?: {
+        timeoutMs?: number;
+    }): Promise<SocketPacketResponseData<ResolveSocketPacketType<TType>>>;
+    onState(listener: (event: ClientSocketStateEvent) => void): () => void;
+    onError(listener: (event: ClientSocketErrorEvent) => void): () => void;
+    onMessage(listener: (event: ClientSocketMessageEvent) => void): () => void;
+    onType<T = any>(type: string, listener: (message: SocketMessage<T>) => void): () => void;
+}
+export declare type SyncTargetType = string;
+export interface SyncTargetDescriptor {
+    type: SyncTargetType;
+    id?: string;
+    intervalMs?: number;
+    meta?: Record<string, unknown>;
+}
+export interface DomainSyncContext {
+    client: ClientSocketV2;
+    now(): number;
+    readSnapshot<T = unknown>(target: SyncTargetDescriptor): T | undefined;
+    writeSnapshot<T = unknown>(target: SyncTargetDescriptor, snapshot: T | undefined): void;
+    requestResync(target: SyncTargetDescriptor): Promise<void>;
+}
+export interface DomainSyncPlan<TTarget extends SyncTargetDescriptor = SyncTargetDescriptor> {
+    readonly domain: string;
+    supports(target: SyncTargetDescriptor): target is TTarget;
+    getKey(target: TTarget): string;
+    getIntervalMs?(target: TTarget): number;
+    onConnected?(target: TTarget, ctx: DomainSyncContext): Promise<void> | void;
+    run(target: TTarget, ctx: DomainSyncContext): Promise<void>;
+    onTrigger?(target: TTarget, message: SocketMessage<any>, ctx: DomainSyncContext): Promise<void>;
+    updateLocalState?(target: TTarget, snapshot: unknown, ctx: DomainSyncContext): void;
+}
+export interface SyncScheduler {
+    start(target: SyncTargetDescriptor): void;
+    stop(target: SyncTargetDescriptor): void;
+    stopAll(): void;
+    list(): SyncTargetDescriptor[];
+    updateLocalSnapshot(target: SyncTargetDescriptor, snapshot: unknown): void;
+}
+export interface KeepAliveLoopControl {
+    start(): void;
+    stop(): void;
+}
+export interface ReconnectController {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+}
+export interface SharedTimerScheduler {
+    schedule(key: string, delayMs: number, task: () => void | Promise<void>): void;
+    cancel(key: string): void;
+    cancelAll(prefix?: string): void;
+}
+export interface ClientSocketRuntime {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    startSync(target: SyncTargetDescriptor): void;
+    stopSync(target: SyncTargetDescriptor): void;
+    stopAllSync(): void;
+    listSyncTargets(): SyncTargetDescriptor[];
+    updateLocalSnapshot(target: SyncTargetDescriptor, snapshot: unknown): void;
+}

package/dist/client-socket-v2/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/device/contracts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `lib/device/contracts.ts`
+ * - client-safe shared device contracts.
+ * - keep this file free from server-only runtime dependencies.
+ */
+export declare type DeviceStatus = '' | 'green' | 'red' | 'yellow';
+export declare type DevicePlatform = '' | 'ios' | 'android' | 'web' | 'macos' | 'windows' | 'linux';
+/**
+ * common device shape shared across websocket client/server contracts.
+ */
+export interface DeviceView {
+    id?: string;
+    name?: string;
+    platform?: DevicePlatform;
+    status?: DeviceStatus;
+    tick?: number;
+    posX?: number;
+    posY?: number;
+    lastActiveAt?: number;
+    connectedAt?: number;
+    disconnectedAt?: number;
+    connId?: string;
+}
+/**
+ * mutable device body accepted by `device.save`.
+ * - `tick` is server-managed and must be ignored when provided by clients.
+ */
+export interface DeviceBody extends Partial<DeviceView> {
+}
+/**
+ * client bootstrap seed.
+ * - `tick` is intentionally blocked because the client must never author it.
+ */
+export declare type DeviceSeed = Omit<DeviceBody, 'tick'> & {
+    tick?: never;
+};

package/dist/lib/device/contracts.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * `lib/device/contracts.ts`
+ * - client-safe shared device contracts.
+ * - keep this file free from server-only runtime dependencies.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/device/types.d.ts

@@ -0,0 +1,55 @@
+import type { InferSocketError, InferSocketRequest, InferSocketResponse, SocketErrorMessage, SocketRequestMessage, SocketResponseMessage } from '../types';
+import type { DeviceBody, DeviceSeed, DeviceView } from './contracts';
+/**
+ * request payload for `device.read`
+ * - omit `id` to read the device linked to the current connection.
+ */
+export interface DeviceGetRequestData {
+    id?: string;
+}
+export interface DeviceSyncRequestData {
+    id?: string;
+    tick?: number;
+}
+declare module '../types' {
+    interface SocketPacketRegistry {
+        'device.save': {
+            request: DeviceBody;
+            response: DeviceView;
+            error: null;
+        };
+        'device.read': {
+            request: DeviceGetRequestData | null;
+            response: DeviceView;
+            error: null;
+        };
+        'device.sync': {
+            request: DeviceSyncRequestData | null;
+            response: null;
+            error: null;
+        };
+    }
+}
+export declare type DeviceSaveType = 'device.save';
+export declare type DeviceSaveResponseData = InferSocketResponse<DeviceSaveType>;
+export declare type DeviceSaveErrorData = InferSocketError<DeviceSaveType>;
+export declare type DeviceSaveInput = InferSocketRequest<DeviceSaveType>;
+export declare type DeviceBootstrapInput = DeviceSeed;
+export declare type DeviceSaveRequestMessage = SocketRequestMessage<DeviceSaveType>;
+export declare type DeviceSaveResponseMessage = SocketResponseMessage<DeviceSaveType>;
+export declare type DeviceSaveErrorMessage = SocketErrorMessage<DeviceSaveType>;
+export declare type DeviceGetType = 'device.read';
+export declare type DeviceGetResponseData = InferSocketResponse<DeviceGetType>;
+export declare type DeviceGetErrorData = InferSocketError<DeviceGetType>;
+export declare type DeviceGetInput = InferSocketRequest<DeviceGetType>;
+export declare type DeviceGetRequestMessage = SocketRequestMessage<DeviceGetType>;
+export declare type DeviceGetResponseMessage = SocketResponseMessage<DeviceGetType>;
+export declare type DeviceGetErrorMessage = SocketErrorMessage<DeviceGetType>;
+export declare type DeviceSyncType = 'device.sync';
+export declare type DeviceSyncResponseData = InferSocketResponse<DeviceSyncType>;
+export declare type DeviceSyncErrorData = InferSocketError<DeviceSyncType>;
+export declare type DeviceSyncInput = InferSocketRequest<DeviceSyncType>;
+export declare type DeviceSyncRequestMessage = SocketRequestMessage<DeviceSyncType>;
+export declare type DeviceSyncResponseMessage = SocketResponseMessage<DeviceSyncType>;
+export declare type DeviceSyncErrorMessage = SocketErrorMessage<DeviceSyncType>;
+export type { DeviceBody, DeviceSeed, DeviceView };

package/dist/lib/device/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });