@camera.ui/transport 0.0.1

package/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2020-2026 seydx <hi@seydx.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# @camera.ui/transport
+
+[![npm](https://img.shields.io/npm/v/@camera.ui/transport?label=npm&logo=npm)](https://www.npmjs.com/package/@camera.ui/transport)
+[![License](https://img.shields.io/github/license/cameraui/clients)](LICENSE.md)
+
+The camera.ui transport layer — a framework-agnostic connection kernel with pluggable transports, reducer-based state, lifecycle effects and worker bridging.
+
+---
+
+*Part of the camera.ui ecosystem - A comprehensive camera management solution.*

package/dist/contract-d-0gfY8v.js

@@ -0,0 +1,43 @@
+//#region src/transports/contract.ts
+function isSameTarget(a, b) {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	if (a.endpoint.url !== b.endpoint.url || a.endpoint.mode !== b.endpoint.mode) return false;
+	if (a.tokens.access !== b.tokens.access) return false;
+	if ((a.tokens.proxySession ?? null) !== (b.tokens.proxySession ?? null)) return false;
+	return true;
+}
+function isEndpointChange(a, b) {
+	if (a === b) return false;
+	if (!a || !b) return true;
+	return a.endpoint.url !== b.endpoint.url || a.endpoint.mode !== b.endpoint.mode;
+}
+function isTokenOnlyChange(a, b) {
+	if (!a || !b) return false;
+	if (isEndpointChange(a, b)) return false;
+	return !isSameTarget(a, b);
+}
+var TransportEmitter = class {
+	listeners = /* @__PURE__ */ new Map();
+	on(event, handler) {
+		let set = this.listeners.get(event);
+		if (!set) {
+			set = /* @__PURE__ */ new Set();
+			this.listeners.set(event, set);
+		}
+		set.add(handler);
+		return () => {
+			set.delete(handler);
+		};
+	}
+	emit(event, payload) {
+		const set = this.listeners.get(event);
+		if (!set) return;
+		for (const fn of [...set]) fn(payload);
+	}
+	clear() {
+		this.listeners.clear();
+	}
+};
+//#endregion
+export { isTokenOnlyChange as i, isEndpointChange as n, isSameTarget as r, TransportEmitter as t };

package/dist/core/kernel.d.ts

@@ -0,0 +1,14 @@
+import { Action, ConnectionPhase, ReducerContext } from './types.js';
+export type Listener = (phase: ConnectionPhase, prev: ConnectionPhase, action: Action) => void;
+export type Unsubscribe = () => void;
+export interface KernelOptions {
+    readonly context: ReducerContext;
+    readonly initial?: ConnectionPhase;
+}
+export interface Kernel {
+    readonly phase: ConnectionPhase;
+    dispatch(action: Action): void;
+    subscribe(listener: Listener): Unsubscribe;
+    dispose(): void;
+}
+export declare function createKernel(options: KernelOptions): Kernel;

package/dist/core/reducer.d.ts

@@ -0,0 +1,2 @@
+import { Action, ConnectionPhase, ReducerContext } from './types.js';
+export declare function reducer(phase: ConnectionPhase, action: Action, ctx: ReducerContext): ConnectionPhase;

package/dist/core/resolver.d.ts

@@ -0,0 +1,5 @@
+import { Endpoint, EndpointMode } from './types.js';
+export declare function sortByPriority(endpoints: readonly Endpoint[]): Endpoint[];
+export declare function isSameEndpoint(a: Endpoint, b: Endpoint): boolean;
+export declare function endpointKey(ep: Endpoint): string;
+export type { EndpointMode };

package/dist/core/types.d.ts

@@ -0,0 +1,109 @@
+export type EndpointMode = 'direct-lan' | 'direct-wan';
+export interface Endpoint {
+    readonly url: string;
+    readonly mode: EndpointMode;
+    readonly priority?: number;
+}
+export interface Tokens {
+    readonly access: string;
+    readonly accessExpiresAt?: number;
+    readonly refresh?: string;
+    readonly refreshExpiresAt?: number;
+    readonly proxySession?: string;
+    readonly proxySessionExpiresAt?: number;
+    readonly proxyRefresh?: string;
+}
+export interface ConnectionTarget {
+    readonly endpoint: Endpoint;
+    readonly tokens: Tokens;
+    readonly meta?: Readonly<Record<string, unknown>>;
+}
+export type TransportId = string;
+export type TransportKind = 'persistent' | 'request' | 'per-resource';
+export interface TransportSpec {
+    readonly id: TransportId;
+    readonly kind: TransportKind;
+    readonly phaseGating: boolean;
+    readonly graceMs?: number;
+}
+export interface TransportStatus {
+    readonly up: boolean;
+    readonly lastError?: string;
+    readonly downSince?: number;
+}
+export type ReconnectCause = 'transport-down' | 'auth-error' | 'network-change' | 'user-retry' | 'endpoint-swap';
+export type ConnectionPhase = {
+    readonly kind: 'idle';
+} | {
+    readonly kind: 'discovering';
+    readonly instanceId: string;
+    readonly attempt: number;
+} | {
+    readonly kind: 'online';
+    readonly instanceId: string;
+    readonly target: ConnectionTarget;
+    readonly transports: ReadonlyMap<TransportId, TransportStatus>;
+} | {
+    readonly kind: 'reconnecting';
+    readonly instanceId: string;
+    readonly lastTarget: ConnectionTarget | null;
+    readonly cause: ReconnectCause;
+    readonly since: number;
+    readonly transports: ReadonlyMap<TransportId, TransportStatus>;
+} | {
+    readonly kind: 'needs-auth';
+    readonly instanceId: string | null;
+    readonly reason: string;
+} | {
+    readonly kind: 'offline';
+    readonly instanceId: string | null;
+    readonly lastError: string;
+    readonly nextRetryAt: number;
+    readonly backoffHint?: BackoffHint;
+};
+export interface BackoffHint {
+    readonly retryAfterMs: number;
+    readonly setAt: number;
+    readonly source?: string;
+}
+export type Action = {
+    readonly type: 'BOOT';
+    readonly instanceId: string;
+} | {
+    readonly type: 'PROBE_SUCCEEDED';
+    readonly endpoint: Endpoint;
+    readonly tokens: Tokens;
+} | {
+    readonly type: 'PROBE_FAILED_ALL';
+    readonly error: string;
+} | {
+    readonly type: 'TRANSPORT_UP';
+    readonly id: TransportId;
+} | {
+    readonly type: 'TRANSPORT_DOWN';
+    readonly id: TransportId;
+    readonly reason: string;
+} | {
+    readonly type: 'TRANSPORT_DOWN_CONFIRMED';
+    readonly id: TransportId;
+} | {
+    readonly type: 'TOKENS_REFRESHED';
+    readonly tokens: Tokens;
+} | {
+    readonly type: 'TOKENS_INVALID';
+    readonly reason: string;
+    readonly transient?: boolean;
+} | {
+    readonly type: 'USER_RETRY';
+} | {
+    readonly type: 'RESET';
+} | {
+    readonly type: 'BACKOFF_HINT';
+    readonly retryAfterMs: number;
+    readonly source?: string;
+};
+export interface ReducerContext {
+    readonly specs: ReadonlyMap<TransportId, TransportSpec>;
+    readonly now: () => number;
+    readonly retryBackoffMs?: (attempt: number) => number;
+}

package/dist/effects/backoff.d.ts

@@ -0,0 +1,14 @@
+import { Kernel } from '../core/kernel.js';
+export type Detach = () => void;
+export interface BackoffOptions {
+    readonly kernel: Kernel;
+    readonly schedule?: readonly number[];
+    readonly now?: () => number;
+    readonly setTimer?: (cb: () => void, ms: number) => unknown;
+    readonly clearTimer?: (handle: unknown) => void;
+    readonly onScheduled?: (attempt: number, delayMs: number) => void;
+    readonly onFire?: (attempt: number) => void;
+    readonly onCancelled?: (reason: 'phase-left-offline' | 'detach' | 'rescheduled') => void;
+    readonly onHintApplied?: (delayMs: number, source?: string) => void;
+}
+export declare function attachBackoff(options: BackoffOptions): Detach;

package/dist/effects/crossTab.d.ts

@@ -0,0 +1,14 @@
+import { Kernel } from '../core/kernel.js';
+import { ConnectionTarget } from '../core/types.js';
+export type Detach = () => void;
+export interface CrossTabSource extends EventTarget {
+}
+export interface CrossTabOptions {
+    readonly kernel: Kernel;
+    readonly key?: string;
+    readonly source?: CrossTabSource;
+    readonly onTokensReceived?: (tokens: ConnectionTarget['tokens']) => void;
+    readonly onResetReceived?: () => void;
+    readonly onError?: (op: 'parse', err: unknown) => void;
+}
+export declare function attachCrossTab(options: CrossTabOptions): Detach;

package/dist/effects/networkChange.d.ts

@@ -0,0 +1,10 @@
+import { Kernel } from '../core/kernel.js';
+export type Detach = () => void;
+export interface NetworkChangeSource extends EventTarget {
+}
+export interface NetworkChangeOptions {
+    readonly kernel: Kernel;
+    readonly source: NetworkChangeSource;
+    readonly onChange: (kernel: Kernel, event: Event) => void;
+}
+export declare function attachNetworkChange(options: NetworkChangeOptions): Detach;

package/dist/effects/persistence.d.ts

@@ -0,0 +1,31 @@
+import { Kernel } from '../core/kernel.js';
+import { ConnectionTarget } from '../core/types.js';
+export type Detach = () => void;
+export interface StorageAdapter {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    del(key: string): void | Promise<void>;
+}
+export interface PersistedTarget {
+    readonly endpoint: ConnectionTarget['endpoint'];
+    readonly tokens: ConnectionTarget['tokens'];
+    readonly savedAt: number;
+    readonly version: 1;
+}
+export interface Persistence {
+    readonly detach: Detach;
+    peek(): ConnectionTarget | null;
+    seed(target: ConnectionTarget): Promise<void>;
+}
+export interface PersistenceOptions {
+    readonly kernel: Kernel;
+    readonly storage: StorageAdapter;
+    readonly key?: string;
+    readonly onRestore?: (restored: ConnectionTarget | null) => void;
+    readonly onPersist?: (target: ConnectionTarget) => void;
+    readonly onClear?: () => void;
+    readonly onError?: (op: 'get' | 'set' | 'del' | 'parse', err: unknown) => void;
+}
+export declare function attachPersistence(options: PersistenceOptions): Persistence;
+export declare function localStorageAdapter(scope?: Storage): StorageAdapter;
+export declare function memoryStorageAdapter(initial?: Record<string, string>): StorageAdapter;

package/dist/effects/presence.d.ts

@@ -0,0 +1,17 @@
+import { Kernel } from '../core/kernel.js';
+export type Detach = () => void;
+export type PresenceCallback = (kernel: Kernel) => void;
+export interface VisibilitySource extends EventTarget {
+    visibilityState?: DocumentVisibilityState;
+}
+export interface PresenceOptions {
+    readonly kernel: Kernel;
+    readonly networkSource?: EventTarget | null;
+    readonly visibilitySource?: VisibilitySource | null;
+    readonly onOnline?: PresenceCallback;
+    readonly onOffline?: PresenceCallback;
+    readonly onVisibilityVisible?: PresenceCallback;
+    readonly onVisibilityHidden?: PresenceCallback;
+}
+export declare const defaultOnNetworkOnline: PresenceCallback;
+export declare function attachPresence(options: PresenceOptions): Detach;

package/dist/effects/probeLoop.d.ts

@@ -0,0 +1,30 @@
+import { Kernel } from '../core/kernel.js';
+import { ConnectionTarget, Endpoint, Tokens } from '../core/types.js';
+import { TimeoutByModeFn } from '../race.js';
+export type Detach = () => void;
+export type ProbeFailureKind = 'transient' | 'needs-auth' | 'fatal' | 'aborted';
+export interface ProbeFailure extends Error {
+    readonly kind: ProbeFailureKind;
+}
+export declare function makeProbeFailure(kind: ProbeFailureKind, message: string): ProbeFailure;
+export declare function isProbeFailure(err: unknown): err is ProbeFailure;
+export interface ProbeContext {
+    readonly endpoint: Endpoint;
+    readonly lastTokens?: Tokens;
+    readonly signal: AbortSignal;
+}
+export interface ProbeLoopOptions {
+    readonly kernel: Kernel;
+    readonly discover: (signal: AbortSignal) => Promise<readonly Endpoint[]>;
+    readonly probe: (ctx: ProbeContext) => Promise<Tokens>;
+    readonly timeoutByMode?: TimeoutByModeFn;
+    readonly onDiscoverStart?: () => void;
+    readonly onDiscoverSuccess?: (pool: readonly Endpoint[]) => void;
+    readonly onDiscoverError?: (err: unknown) => void;
+    readonly onProbeStart?: (endpoint: Endpoint) => void;
+    readonly onProbeSuccess?: (endpoint: Endpoint, tokens: Tokens) => void;
+    readonly onProbeError?: (endpoint: Endpoint, err: unknown) => void;
+    readonly onAllFailed?: (reason: string) => void;
+    readonly lastTarget?: () => ConnectionTarget | null;
+}
+export declare function attachProbeLoop(options: ProbeLoopOptions): Detach;

package/dist/effects/tokenLifecycle.d.ts

@@ -0,0 +1,39 @@
+import { Kernel } from '../core/kernel.js';
+import { ConnectionTarget, Tokens } from '../core/types.js';
+import { Transport } from '../transports/contract.js';
+export type RefreshReason = 'proactive' | 'auth-error';
+export interface TokenLifecycleOptions {
+    readonly kernel: Kernel;
+    readonly transports: readonly Transport[];
+    readonly refresh: (target: ConnectionTarget, reason: RefreshReason) => Promise<Tokens>;
+    readonly graceMs?: number;
+    readonly isTransientError?: (err: unknown) => boolean;
+    readonly maxTransientRetries?: number;
+    readonly transientRetryDelayMs?: number;
+    readonly now?: () => number;
+    readonly setTimer?: (cb: () => void, ms: number) => unknown;
+    readonly clearTimer?: (handle: unknown) => void;
+    readonly acquireRefreshLock?: <T>(fn: () => Promise<T>) => Promise<T>;
+    readonly getLatestTokens?: () => Tokens | null;
+    readonly onRefreshStart?: (reason: RefreshReason) => void;
+    readonly onRefreshSuccess?: (reason: RefreshReason, tokens: Tokens) => void;
+    readonly onRefreshSkipped?: (reason: RefreshReason, tokens: Tokens) => void;
+    readonly onRefreshError?: (reason: RefreshReason, error: unknown, info: {
+        transient: boolean;
+        retriesLeft: number;
+        willRetry: boolean;
+    }) => void;
+    readonly onScheduled?: (delayMs: number, expiresAt: number) => void;
+    readonly onWakeChecked?: (info: {
+        decision: 'refresh-now' | 'still-fresh' | 'no-target' | 'no-expiry';
+        remainingMs?: number;
+        phase: string;
+    }) => void;
+    readonly onTriggerSkipped?: (reason: RefreshReason, why: 'detached' | 'already-inflight' | 'no-target', phase: string) => void;
+}
+export type Detach = () => void;
+export interface TokenLifecycle {
+    readonly detach: () => void;
+    readonly wake: () => void;
+}
+export declare function attachTokenLifecycle(options: TokenLifecycleOptions): TokenLifecycle;

package/dist/effects/transportSync.d.ts

@@ -0,0 +1,11 @@
+import { Kernel } from '../core/kernel.js';
+import { ConnectionTarget } from '../core/types.js';
+import { Transport } from '../transports/contract.js';
+export type Detach = () => void;
+export interface TransportSyncOptions {
+    readonly kernel: Kernel;
+    readonly transports: readonly Transport[];
+    readonly onError?: (transport: Transport, target: ConnectionTarget | null, error: unknown) => void;
+    readonly onApplied?: (target: ConnectionTarget | null) => void;
+}
+export declare function attachTransportSync(options: TransportSyncOptions): Detach;

package/dist/effects/transportWatchdog.d.ts

@@ -0,0 +1,16 @@
+import { Kernel } from '../core/kernel.js';
+import { TransportId } from '../core/types.js';
+import { Transport } from '../transports/contract.js';
+export type Detach = () => void;
+export type WatchdogClearReason = 'up' | 'detach' | 'phase-change';
+export interface TransportWatchdogOptions {
+    readonly kernel: Kernel;
+    readonly transports: readonly Transport[];
+    readonly defaultGraceMs?: number;
+    readonly setTimer?: (cb: () => void, ms: number) => unknown;
+    readonly clearTimer?: (handle: unknown) => void;
+    readonly onGraceStarted?: (id: TransportId, graceMs: number) => void;
+    readonly onGraceCleared?: (id: TransportId, reason: WatchdogClearReason) => void;
+    readonly onConfirmed?: (id: TransportId) => void;
+}
+export declare function attachTransportWatchdog(options: TransportWatchdogOptions): Detach;

package/dist/effects/workerBridge.d.ts

@@ -0,0 +1,17 @@
+import { Kernel } from '../core/kernel.js';
+import { WorkerHost } from '../worker/protocol.js';
+export type Detach = () => void;
+export interface WorkerBridgeOptions {
+    readonly kernel: Kernel;
+    readonly hosts: () => Iterable<WorkerHost>;
+    readonly listenForResyncRequests?: boolean;
+    readonly onBroadcast?: (generation: number, hostCount: number) => void;
+    readonly onSyncHost?: (generation: number) => void;
+}
+export interface WorkerBridge {
+    readonly detach: Detach;
+    syncHost(host: WorkerHost): void;
+    syncAll(): void;
+    revalidateWorkers(): void;
+}
+export declare function attachWorkerBridge(options: WorkerBridgeOptions): WorkerBridge;

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { createKernel } from './core/kernel.js';
+export { reducer } from './core/reducer.js';
+export { endpointKey, isSameEndpoint, sortByPriority } from './core/resolver.js';
+export { attachBackoff } from './effects/backoff.js';
+export { attachCrossTab } from './effects/crossTab.js';
+export { attachNetworkChange } from './effects/networkChange.js';
+export { attachPersistence, localStorageAdapter, memoryStorageAdapter } from './effects/persistence.js';
+export { attachPresence, defaultOnNetworkOnline } from './effects/presence.js';
+export { attachProbeLoop, isProbeFailure, makeProbeFailure } from './effects/probeLoop.js';
+export { attachTokenLifecycle } from './effects/tokenLifecycle.js';
+export { attachTransportSync } from './effects/transportSync.js';
+export { attachTransportWatchdog } from './effects/transportWatchdog.js';
+export { attachWorkerBridge } from './effects/workerBridge.js';
+export { DEFAULT_RACE_TIMEOUT_BY_MODE, raceFirst, RaceFirstError } from './race.js';
+export { isEndpointChange, isSameTarget, isTokenOnlyChange, TransportEmitter } from './transports/contract.js';
+export type { Action, BackoffHint, ConnectionPhase, ConnectionTarget, Endpoint, EndpointMode, ReconnectCause, ReducerContext, Tokens, TransportId, TransportKind, TransportSpec, TransportStatus, } from './core/types.js';
+export type { Kernel, KernelOptions, Listener, Unsubscribe } from './core/kernel.js';
+export type { BackoffOptions } from './effects/backoff.js';
+export type { CrossTabOptions, CrossTabSource } from './effects/crossTab.js';
+export type { NetworkChangeOptions, NetworkChangeSource } from './effects/networkChange.js';
+export type { PersistedTarget, Persistence, PersistenceOptions, StorageAdapter } from './effects/persistence.js';
+export type { PresenceCallback, PresenceOptions, VisibilitySource } from './effects/presence.js';
+export type { ProbeContext, ProbeFailure, ProbeFailureKind, ProbeLoopOptions } from './effects/probeLoop.js';
+export type { Detach, RefreshReason, TokenLifecycle, TokenLifecycleOptions } from './effects/tokenLifecycle.js';
+export type { TransportSyncOptions } from './effects/transportSync.js';
+export type { TransportWatchdogOptions, WatchdogClearReason } from './effects/transportWatchdog.js';
+export type { WorkerBridge, WorkerBridgeOptions } from './effects/workerBridge.js';
+export type { RaceCandidate, RaceFirstOptions, RaceFirstResult, TimeoutByModeFn } from './race.js';
+export type { KernelSyncMessage, KernelSyncRequestMessage, MessageSource, WorkerHost, WorkerMessage } from './worker/protocol.js';
+export type { PerResourceTransport, Transport, TransportEvent, TransportEventHandler, TransportEventPayload } from './transports/contract.js';