@abloatai/humans 0.37.0

package/src/local/NetworkMonitor.ts

@@ -0,0 +1,88 @@
+/**
+ * NetworkMonitor tracks network connectivity and reports it through events.
+ * It listens to the browser's online and offline events, and it also watches
+ * for a tab becoming visible again: after a laptop sleep/wake or a long spell
+ * in the background, the WebSocket can die silently without an offline event
+ * firing, so returning to the tab emits a recovery signal the store can act on.
+ */
+
+import { EventEmitter } from 'events';
+import { globalRuntime } from './context.js';
+import type { RuntimeContext } from './RuntimeContext.js';
+
+export class NetworkMonitor extends EventEmitter {
+  // Only `navigator.onLine === false` means offline. Node 18+ exposes a global
+  // `navigator` with `onLine === undefined`, so the naive `navigator.onLine`
+  // would seed `false` (offline) on every server client — start optimistic.
+  private isOnline = !(typeof navigator !== 'undefined' && navigator.onLine === false);
+  private lastOnlineCheck: Date = new Date();
+
+  constructor(private readonly runtime: RuntimeContext = globalRuntime) {
+    super();
+    this.setupListeners();
+  }
+
+  private handleOnline = (): void => {
+    const wasOffline = !this.isOnline;
+    this.isOnline = true;
+    this.lastOnlineCheck = new Date();
+    if (wasOffline) {
+      this.runtime.logger.info('Network connection restored');
+      this.emit('online');
+    }
+  };
+
+  private handleOffline = (): void => {
+    const wasOnline = this.isOnline;
+    this.isOnline = false;
+    if (wasOnline) {
+      // Symmetric with 'Network connection restored' (info) — expected,
+      // transient connectivity state, not an actionable warning.
+      this.runtime.logger.info('Network connection lost');
+      this.emit('offline');
+    }
+  };
+
+  /**
+   * When the tab becomes visible, the WebSocket may have silently died
+   * (e.g., laptop sleep/wake, long background). Browser online/offline events
+   * don't fire in this case because the network itself didn't change.
+   * Emit 'visibility_online' so SyncedStore can check and recover.
+   */
+  private handleVisibilityChange = (): void => {
+    if (document.visibilityState !== 'visible') return;
+
+    // Update navigator.onLine state — it may have changed while hidden
+    this.isOnline = navigator.onLine;
+    this.lastOnlineCheck = new Date();
+
+    if (this.isOnline) {
+      this.runtime.logger.info('Tab became visible with network available — emitting visibility_online');
+      this.emit('visibility_online');
+    }
+  };
+
+  private setupListeners(): void {
+    if (typeof window === 'undefined') return;
+    window.addEventListener('online', this.handleOnline);
+    window.addEventListener('offline', this.handleOffline);
+    document.addEventListener('visibilitychange', this.handleVisibilityChange);
+  }
+
+  getStatus(): boolean {
+    return this.isOnline;
+  }
+
+  getLastOnlineTime(): Date {
+    return this.lastOnlineCheck;
+  }
+
+  dispose(): void {
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('online', this.handleOnline);
+      window.removeEventListener('offline', this.handleOffline);
+      document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+    }
+    this.removeAllListeners();
+  }
+}

package/src/local/RuntimeContext.ts

@@ -0,0 +1,141 @@
+/**
+ * RuntimeContext — Runtime dependency container
+ *
+ * All SDK classes receive this context at construction time.
+ * It bundles every injectable dependency so constructors stay clean.
+ */
+
+import type {
+  Logger,
+  ObservabilityProvider,
+  Analytics,
+  SessionErrorDetector,
+  OnlineStatusProvider,
+  ModelDebugLoggerContract,
+  MutationExecutor,
+  RuntimeConfig,
+  BreadcrumbLevel,
+  BreadcrumbCategory,
+  SpanAttributes,
+} from './interfaces/index.js';
+import type { ModelMetadata } from '@abloatai/transaction/types';
+import { AbloSessionError } from '@abloatai/transaction/errors';
+
+export interface RuntimeContext {
+  /** Structured logger */
+  logger: Logger;
+
+  /** Error tracking & performance monitoring */
+  observability: ObservabilityProvider;
+
+  /** Product analytics (optional) */
+  analytics?: Analytics;
+
+  /** Session error detection for auth redirect decisions */
+  sessionErrorDetector: SessionErrorDetector;
+
+  /** Network connectivity detection */
+  onlineStatus: OnlineStatusProvider;
+
+  /** Model operation debug logging (optional, dev-only) */
+  modelDebugLogger?: ModelDebugLoggerContract;
+
+  /** Backend mutation transport (GraphQL, REST, etc.) */
+  mutationExecutor: MutationExecutor;
+
+  /** Application-specific sync configuration */
+  config: RuntimeConfig;
+
+  /**
+   * Model metadata lookup. Injected by the client (it wires this from its
+   * `ModelRegistry`) so the settlement core can resolve a model's metadata
+   * without importing the registry — the dependency inversion that keeps the
+   * core free of the client's `Model` layer (ADR 0013).
+   */
+  getModelMetadata: (name: string) => ModelMetadata | undefined;
+}
+
+// ─────────────────────────────────────────────
+// No-op defaults for optional dependencies
+// ─────────────────────────────────────────────
+
+// Re-exported, not redeclared. `@abloatai/transaction/logger` owns the no-op that
+// sits beside the `Logger` port. This package held a second, behaviourally
+// identical copy, and half of it imported the canonical one while the other
+// half imported this — so any change of semantics there would have reached
+// only one side, invisibly, because the identifier reads the same at both.
+export { noopLogger } from '@abloatai/transaction/logger';
+
+/** No-op observability — silently discards all observability calls */
+export const noopObservability: ObservabilityProvider = {
+  setContext() {},
+  setConnectionState() {},
+  breadcrumb() {},
+  captureRollback() {},
+  captureMutationFailure() {},
+  captureBootstrapFailure() {},
+  captureReconciliation() {},
+  captureDeltaRetryExhausted() {},
+  captureWebSocketError() {},
+  captureSelfHealing() {},
+  captureClaim() {},
+  captureConflict() {},
+  captureCommitZeroSyncId() {},
+  startSpan<T>(_name: string, _op: string, fn: () => T, _attributes?: SpanAttributes): T {
+    return fn();
+  },
+  async startSpanAsync<T>(
+    _name: string,
+    _op: string,
+    fn: () => Promise<T>,
+    _attributes?: SpanAttributes
+  ): Promise<T> {
+    return fn();
+  },
+};
+
+/** No-op analytics — silently discards all analytics calls */
+export const noopAnalytics: Analytics = {
+  capture() {},
+};
+
+/** Browser-native online status provider */
+export const browserOnlineStatus: OnlineStatusProvider = {
+  isOnline(): boolean {
+    // Only `navigator.onLine === false` is the MDN-reliable "definitely offline"
+    // signal. Don't use `!navigator.onLine`: Node 18+ exposes a global
+    // `navigator` whose `onLine` is `undefined`, which `!` would read as offline —
+    // wedging every Node/server client (agents, worker, MCP) into a false offline.
+    return !(typeof navigator !== 'undefined' && navigator.onLine === false);
+  },
+};
+
+/** Session error detector — delegates to AbloSessionError so detection is
+ *  code-aware (only genuine session/JWT expiry counts), not a blunt 401/403. */
+export const defaultSessionErrorDetector: SessionErrorDetector = {
+  isSessionError(error: unknown): boolean {
+    if (error && typeof error === 'object' && 'isSessionError' in error) {
+      return (error as { isSessionError: boolean }).isSessionError;
+    }
+    return false;
+  },
+  isSessionErrorResponse(status: number, body?: string): boolean {
+    return AbloSessionError.isSessionErrorResponse(status, body);
+  },
+};
+
+/**
+ * Fallback config used when the context is read before
+ * `createSyncEngine(...)` has initialized it (tests, early-boot code
+ * paths). An empty `modelCreatePriority` means every model falls through
+ * to `defaultCreatePriority`, so ordering is flat — fine for tests that
+ * never exercise FK ordering; consumers who do rely on it should finish
+ * wiring the engine before the first `create()` fires.
+ */
+export const emptyConfig: RuntimeConfig = {
+  modelCreatePriority: new Map(),
+  defaultCreatePriority: 40,
+  defaultNonCreatePriority: 50,
+  essentialFields: {},
+  classNameFallbackMap: {},
+};