@wireflowapp/core 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @wireflowapp/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The foundational core package for **Wireflow**, providing common connection types, centralized configuration management, and robust retry orchestration.
+
+## Features
+
+- **Standard Connection Status**: Defines uniform `"Idle" | "Connecting" | "Connected" | "Failed"` statuses.
+- **RetryManager**: Authoritative retry scheduling, preventing duplicate timers and race conditions.
+- **WireFlowManager**: Hierarchical configuration manager honoring hook overrides > manager defaults > library defaults.
+- **Zero Runtime Dependencies**: Ultra-lightweight and framework-agnostic.
+
+## Installation
+
+```bash
+pnpm add @wireflowapp/core
+```
+
+## Quick Start
+
+```ts
+import { WireFlowManager, RetryManager, ConnectionStatus } from "@wireflowapp/core";
+
+// Centralized configuration
+const manager = new WireFlowManager({
+  retryAttempts: 3,
+  retryDelay: 2000,
+});
+WireFlowManager.setDefault(manager);
+```

package/dist/index.d.mts

@@ -0,0 +1,200 @@
+/**
+ * Shared connection status across all Wireflow transports and framework adapters.
+ */
+type ConnectionStatus = "Idle" | "Connecting" | "Connected" | "Failed";
+/**
+ * Standard public connection API surface returned by Wireflow connections.
+ */
+interface ConnectionResult {
+    /**
+     * Current status of the connection.
+     */
+    readonly status: ConnectionStatus;
+    /**
+     * Initiates an initial connection attempt.
+     */
+    connect: () => void;
+    /**
+     * Manually triggers a retry attempt if currently idle or failed.
+     * Does nothing if already connected or currently connecting.
+     */
+    retry: () => void;
+    /**
+     * Cleanly disconnects the active connection and aborts pending retries.
+     */
+    disconnect: () => void;
+}
+/**
+ * Shared configuration options for connection and retry policies.
+ */
+interface WireFlowConfig {
+    /**
+     * Number of retry attempts after the initial failure.
+     * Total max attempts = retryAttempts + 1.
+     * @default 5
+     */
+    retryAttempts?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     * @default 3000
+     */
+    retryDelay?: number;
+    /**
+     * Whether to automatically connect upon creation or mount.
+     * @default true
+     */
+    autoConnect?: boolean;
+    /**
+     * Whether to automatically schedule retries when an established connection drops unexpectedly.
+     * @default true
+     */
+    retryOnDisconnect?: boolean;
+}
+/**
+ * Resolved, non-nullable Wireflow configuration with library defaults applied.
+ */
+interface ResolvedWireFlowConfig {
+    retryAttempts: number;
+    retryDelay: number;
+    autoConnect: boolean;
+    retryOnDisconnect: boolean;
+}
+interface WireFlowConnection extends ConnectionResult {
+}
+/**
+ * Default configuration values defined by the Wireflow specification.
+ */
+declare const defaultConfig: Required<WireFlowConfig>;
+declare const DEFAULT_WIREFLOW_CONFIG: ResolvedWireFlowConfig;
+
+interface RetryManagerOptions {
+    /**
+     * Number of retries permitted after initial connection failure.
+     * Total attempts = initial attempt (1) + retryAttempts.
+     * @default 5
+     */
+    retryAttempts?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     * @default 3000
+     */
+    retryDelay?: number;
+    /**
+     * Callback fired right before a retry timer starts.
+     */
+    onRetryAttempt?: (attempt: number, maxAttempts: number, delay: number) => void;
+    /**
+     * Callback fired when all retry attempts have been exhausted.
+     */
+    onExhausted?: () => void;
+}
+/**
+ * Reusable retry coordinator managing backoff timers, attempt tracking,
+ * and exhaustion callbacks.
+ */
+declare class RetryManager {
+    private _maxAttempts;
+    private _delay;
+    private _currentAttempt;
+    private _timer;
+    private _onRetryAttempt?;
+    private _onExhausted?;
+    constructor(options?: RetryManagerOptions);
+    /**
+     * Number of retries executed or currently scheduled in this retry cycle.
+     */
+    get attempts(): number;
+    /**
+     * Configured maximum number of retry attempts.
+     */
+    get maxAttempts(): number;
+    /**
+     * Configured delay in milliseconds.
+     */
+    get delay(): number;
+    /**
+     * Indicates whether a retry delay timer is currently active.
+     */
+    get isRetrying(): boolean;
+    /**
+     * Indicates whether all configured retry attempts have been used up.
+     */
+    isExhausted(): boolean;
+    /**
+     * Dynamically update configuration if needed.
+     */
+    updateConfig(options: Partial<RetryManagerOptions>): void;
+    /**
+     * Schedules the next retry execution after `retryDelay` ms.
+     * Prevents duplicate timers if a retry is already in flight.
+     * If all attempts are exhausted, triggers `onExhausted` and returns false.
+     *
+     * @param action The connection attempt function to invoke when the timer fires.
+     * @returns `true` if a retry was scheduled; `false` if already scheduled or exhausted.
+     */
+    scheduleRetry(action: () => void | Promise<void>): boolean;
+    /**
+     * Cancels any pending scheduled retry timer without resetting the attempt counter.
+     */
+    cancel(): void;
+    /**
+     * Resets the attempt counter to 0 and cancels any active retry timer.
+     * Should be called when a connection successfully connects or when manually disconnecting.
+     */
+    reset(): void;
+    /**
+     * Disposes of all internal timers and callbacks.
+     */
+    dispose(): void;
+}
+
+/**
+ * WireFlowManager coordinates centralized configuration defaults for Wireflow
+ * connections across an application.
+ *
+ * It enforces the configuration resolution priority:
+ * 1. Hook/Client-specific options (highest)
+ * 2. WireFlowManager configuration (middle)
+ * 3. Library defaults (baseline)
+ *
+ * Actual transport connection lifecycles remain encapsulated within
+ * transport-specific clients.
+ */
+declare class WireFlowManager {
+    private static defaultInstance;
+    private _config;
+    constructor(customConfig?: WireFlowConfig);
+    /**
+     * Retrieves the current configuration defaults held by this manager instance.
+     */
+    get config(): ResolvedWireFlowConfig;
+    /**
+     * Updates one or more configuration defaults on this manager instance.
+     */
+    updateConfig(newConfig: WireFlowConfig): void;
+    /**
+     * Resolves final configuration by merging specific options with manager defaults
+     * and base library defaults.
+     *
+     * Priority:
+     * 1. overrideConfig (hook or client specific)
+     * 2. this._config (manager instance defaults)
+     * 3. DEFAULT_WIREFLOW_CONFIG (library defaults)
+     */
+    resolveConfig(overrideConfig?: WireFlowConfig): ResolvedWireFlowConfig;
+    /**
+     * Static helper to resolve options directly against the default singleton
+     * manager (if set) or library defaults.
+     */
+    static resolve(overrideConfig?: WireFlowConfig): ResolvedWireFlowConfig;
+    /**
+     * Assigns an optional global default WireFlowManager instance.
+     */
+    static setDefault(manager: WireFlowManager | null): void;
+    /**
+     * Gets the current global default WireFlowManager instance, if one was set.
+     */
+    static getDefault(): WireFlowManager | null;
+}
+
+export { type ConnectionResult, type ConnectionStatus, DEFAULT_WIREFLOW_CONFIG, type ResolvedWireFlowConfig, RetryManager, type RetryManagerOptions, type WireFlowConfig, type WireFlowConnection, WireFlowManager, defaultConfig };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Shared connection status across all Wireflow transports and framework adapters.
+ */
+type ConnectionStatus = "Idle" | "Connecting" | "Connected" | "Failed";
+/**
+ * Standard public connection API surface returned by Wireflow connections.
+ */
+interface ConnectionResult {
+    /**
+     * Current status of the connection.
+     */
+    readonly status: ConnectionStatus;
+    /**
+     * Initiates an initial connection attempt.
+     */
+    connect: () => void;
+    /**
+     * Manually triggers a retry attempt if currently idle or failed.
+     * Does nothing if already connected or currently connecting.
+     */
+    retry: () => void;
+    /**
+     * Cleanly disconnects the active connection and aborts pending retries.
+     */
+    disconnect: () => void;
+}
+/**
+ * Shared configuration options for connection and retry policies.
+ */
+interface WireFlowConfig {
+    /**
+     * Number of retry attempts after the initial failure.
+     * Total max attempts = retryAttempts + 1.
+     * @default 5
+     */
+    retryAttempts?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     * @default 3000
+     */
+    retryDelay?: number;
+    /**
+     * Whether to automatically connect upon creation or mount.
+     * @default true
+     */
+    autoConnect?: boolean;
+    /**
+     * Whether to automatically schedule retries when an established connection drops unexpectedly.
+     * @default true
+     */
+    retryOnDisconnect?: boolean;
+}
+/**
+ * Resolved, non-nullable Wireflow configuration with library defaults applied.
+ */
+interface ResolvedWireFlowConfig {
+    retryAttempts: number;
+    retryDelay: number;
+    autoConnect: boolean;
+    retryOnDisconnect: boolean;
+}
+interface WireFlowConnection extends ConnectionResult {
+}
+/**
+ * Default configuration values defined by the Wireflow specification.
+ */
+declare const defaultConfig: Required<WireFlowConfig>;
+declare const DEFAULT_WIREFLOW_CONFIG: ResolvedWireFlowConfig;
+
+interface RetryManagerOptions {
+    /**
+     * Number of retries permitted after initial connection failure.
+     * Total attempts = initial attempt (1) + retryAttempts.
+     * @default 5
+     */
+    retryAttempts?: number;
+    /**
+     * Delay in milliseconds between retry attempts.
+     * @default 3000
+     */
+    retryDelay?: number;
+    /**
+     * Callback fired right before a retry timer starts.
+     */
+    onRetryAttempt?: (attempt: number, maxAttempts: number, delay: number) => void;
+    /**
+     * Callback fired when all retry attempts have been exhausted.
+     */
+    onExhausted?: () => void;
+}
+/**
+ * Reusable retry coordinator managing backoff timers, attempt tracking,
+ * and exhaustion callbacks.
+ */
+declare class RetryManager {
+    private _maxAttempts;
+    private _delay;
+    private _currentAttempt;
+    private _timer;
+    private _onRetryAttempt?;
+    private _onExhausted?;
+    constructor(options?: RetryManagerOptions);
+    /**
+     * Number of retries executed or currently scheduled in this retry cycle.
+     */
+    get attempts(): number;
+    /**
+     * Configured maximum number of retry attempts.
+     */
+    get maxAttempts(): number;
+    /**
+     * Configured delay in milliseconds.
+     */
+    get delay(): number;
+    /**
+     * Indicates whether a retry delay timer is currently active.
+     */
+    get isRetrying(): boolean;
+    /**
+     * Indicates whether all configured retry attempts have been used up.
+     */
+    isExhausted(): boolean;
+    /**
+     * Dynamically update configuration if needed.
+     */
+    updateConfig(options: Partial<RetryManagerOptions>): void;
+    /**
+     * Schedules the next retry execution after `retryDelay` ms.
+     * Prevents duplicate timers if a retry is already in flight.
+     * If all attempts are exhausted, triggers `onExhausted` and returns false.
+     *
+     * @param action The connection attempt function to invoke when the timer fires.
+     * @returns `true` if a retry was scheduled; `false` if already scheduled or exhausted.
+     */
+    scheduleRetry(action: () => void | Promise<void>): boolean;
+    /**
+     * Cancels any pending scheduled retry timer without resetting the attempt counter.
+     */
+    cancel(): void;
+    /**
+     * Resets the attempt counter to 0 and cancels any active retry timer.
+     * Should be called when a connection successfully connects or when manually disconnecting.
+     */
+    reset(): void;
+    /**
+     * Disposes of all internal timers and callbacks.
+     */
+    dispose(): void;
+}
+
+/**
+ * WireFlowManager coordinates centralized configuration defaults for Wireflow
+ * connections across an application.
+ *
+ * It enforces the configuration resolution priority:
+ * 1. Hook/Client-specific options (highest)
+ * 2. WireFlowManager configuration (middle)
+ * 3. Library defaults (baseline)
+ *
+ * Actual transport connection lifecycles remain encapsulated within
+ * transport-specific clients.
+ */
+declare class WireFlowManager {
+    private static defaultInstance;
+    private _config;
+    constructor(customConfig?: WireFlowConfig);
+    /**
+     * Retrieves the current configuration defaults held by this manager instance.
+     */
+    get config(): ResolvedWireFlowConfig;
+    /**
+     * Updates one or more configuration defaults on this manager instance.
+     */
+    updateConfig(newConfig: WireFlowConfig): void;
+    /**
+     * Resolves final configuration by merging specific options with manager defaults
+     * and base library defaults.
+     *
+     * Priority:
+     * 1. overrideConfig (hook or client specific)
+     * 2. this._config (manager instance defaults)
+     * 3. DEFAULT_WIREFLOW_CONFIG (library defaults)
+     */
+    resolveConfig(overrideConfig?: WireFlowConfig): ResolvedWireFlowConfig;
+    /**
+     * Static helper to resolve options directly against the default singleton
+     * manager (if set) or library defaults.
+     */
+    static resolve(overrideConfig?: WireFlowConfig): ResolvedWireFlowConfig;
+    /**
+     * Assigns an optional global default WireFlowManager instance.
+     */
+    static setDefault(manager: WireFlowManager | null): void;
+    /**
+     * Gets the current global default WireFlowManager instance, if one was set.
+     */
+    static getDefault(): WireFlowManager | null;
+}
+
+export { type ConnectionResult, type ConnectionStatus, DEFAULT_WIREFLOW_CONFIG, type ResolvedWireFlowConfig, RetryManager, type RetryManagerOptions, type WireFlowConfig, type WireFlowConnection, WireFlowManager, defaultConfig };

package/dist/index.js

@@ -0,0 +1,244 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  DEFAULT_WIREFLOW_CONFIG: () => DEFAULT_WIREFLOW_CONFIG,
+  RetryManager: () => RetryManager,
+  WireFlowManager: () => WireFlowManager,
+  defaultConfig: () => defaultConfig
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types/index.ts
+var defaultConfig = Object.freeze({
+  autoConnect: true,
+  retryOnDisconnect: true,
+  retryAttempts: 5,
+  retryDelay: 3e3
+});
+var DEFAULT_WIREFLOW_CONFIG = defaultConfig;
+
+// src/retry/RetryManager.ts
+var RetryManager = class {
+  _maxAttempts;
+  _delay;
+  _currentAttempt = 0;
+  _timer = null;
+  _onRetryAttempt;
+  _onExhausted;
+  constructor(options = {}) {
+    this._maxAttempts = Math.max(0, options.retryAttempts ?? DEFAULT_WIREFLOW_CONFIG.retryAttempts);
+    this._delay = Math.max(0, options.retryDelay ?? DEFAULT_WIREFLOW_CONFIG.retryDelay);
+    this._onRetryAttempt = options.onRetryAttempt;
+    this._onExhausted = options.onExhausted;
+  }
+  /**
+   * Number of retries executed or currently scheduled in this retry cycle.
+   */
+  get attempts() {
+    return this._currentAttempt;
+  }
+  /**
+   * Configured maximum number of retry attempts.
+   */
+  get maxAttempts() {
+    return this._maxAttempts;
+  }
+  /**
+   * Configured delay in milliseconds.
+   */
+  get delay() {
+    return this._delay;
+  }
+  /**
+   * Indicates whether a retry delay timer is currently active.
+   */
+  get isRetrying() {
+    return this._timer !== null;
+  }
+  /**
+   * Indicates whether all configured retry attempts have been used up.
+   */
+  isExhausted() {
+    return this._currentAttempt >= this._maxAttempts;
+  }
+  /**
+   * Dynamically update configuration if needed.
+   */
+  updateConfig(options) {
+    if (typeof options.retryAttempts === "number") {
+      this._maxAttempts = Math.max(0, options.retryAttempts);
+    }
+    if (typeof options.retryDelay === "number") {
+      this._delay = Math.max(0, options.retryDelay);
+    }
+    if (options.onRetryAttempt !== void 0) {
+      this._onRetryAttempt = options.onRetryAttempt;
+    }
+    if (options.onExhausted !== void 0) {
+      this._onExhausted = options.onExhausted;
+    }
+  }
+  /**
+   * Schedules the next retry execution after `retryDelay` ms.
+   * Prevents duplicate timers if a retry is already in flight.
+   * If all attempts are exhausted, triggers `onExhausted` and returns false.
+   *
+   * @param action The connection attempt function to invoke when the timer fires.
+   * @returns `true` if a retry was scheduled; `false` if already scheduled or exhausted.
+   */
+  scheduleRetry(action) {
+    if (this._timer !== null) {
+      return false;
+    }
+    if (this.isExhausted()) {
+      this._onExhausted?.();
+      return false;
+    }
+    this._currentAttempt += 1;
+    this._onRetryAttempt?.(this._currentAttempt, this._maxAttempts, this._delay);
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      try {
+        const result = action();
+        if (result instanceof Promise) {
+          result.catch(() => {
+          });
+        }
+      } catch {
+      }
+    }, this._delay);
+    return true;
+  }
+  /**
+   * Cancels any pending scheduled retry timer without resetting the attempt counter.
+   */
+  cancel() {
+    if (this._timer !== null) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+  /**
+   * Resets the attempt counter to 0 and cancels any active retry timer.
+   * Should be called when a connection successfully connects or when manually disconnecting.
+   */
+  reset() {
+    this.cancel();
+    this._currentAttempt = 0;
+  }
+  /**
+   * Disposes of all internal timers and callbacks.
+   */
+  dispose() {
+    this.reset();
+    this._onRetryAttempt = void 0;
+    this._onExhausted = void 0;
+  }
+};
+
+// src/manager/WireFlowManager.ts
+var WireFlowManager = class _WireFlowManager {
+  static defaultInstance = null;
+  _config;
+  constructor(customConfig = {}) {
+    this._config = {
+      retryAttempts: customConfig.retryAttempts ?? DEFAULT_WIREFLOW_CONFIG.retryAttempts,
+      retryDelay: customConfig.retryDelay ?? DEFAULT_WIREFLOW_CONFIG.retryDelay,
+      autoConnect: customConfig.autoConnect ?? DEFAULT_WIREFLOW_CONFIG.autoConnect,
+      retryOnDisconnect: customConfig.retryOnDisconnect ?? DEFAULT_WIREFLOW_CONFIG.retryOnDisconnect
+    };
+  }
+  /**
+   * Retrieves the current configuration defaults held by this manager instance.
+   */
+  get config() {
+    return { ...this._config };
+  }
+  /**
+   * Updates one or more configuration defaults on this manager instance.
+   */
+  updateConfig(newConfig) {
+    if (newConfig.retryAttempts !== void 0) {
+      this._config.retryAttempts = Math.max(0, newConfig.retryAttempts);
+    }
+    if (newConfig.retryDelay !== void 0) {
+      this._config.retryDelay = Math.max(0, newConfig.retryDelay);
+    }
+    if (newConfig.autoConnect !== void 0) {
+      this._config.autoConnect = newConfig.autoConnect;
+    }
+    if (newConfig.retryOnDisconnect !== void 0) {
+      this._config.retryOnDisconnect = newConfig.retryOnDisconnect;
+    }
+  }
+  /**
+   * Resolves final configuration by merging specific options with manager defaults
+   * and base library defaults.
+   *
+   * Priority:
+   * 1. overrideConfig (hook or client specific)
+   * 2. this._config (manager instance defaults)
+   * 3. DEFAULT_WIREFLOW_CONFIG (library defaults)
+   */
+  resolveConfig(overrideConfig) {
+    return {
+      retryAttempts: overrideConfig?.retryAttempts ?? this._config.retryAttempts,
+      retryDelay: overrideConfig?.retryDelay ?? this._config.retryDelay,
+      autoConnect: overrideConfig?.autoConnect ?? this._config.autoConnect,
+      retryOnDisconnect: overrideConfig?.retryOnDisconnect ?? this._config.retryOnDisconnect
+    };
+  }
+  /**
+   * Static helper to resolve options directly against the default singleton
+   * manager (if set) or library defaults.
+   */
+  static resolve(overrideConfig) {
+    if (_WireFlowManager.defaultInstance) {
+      return _WireFlowManager.defaultInstance.resolveConfig(overrideConfig);
+    }
+    return {
+      retryAttempts: overrideConfig?.retryAttempts ?? DEFAULT_WIREFLOW_CONFIG.retryAttempts,
+      retryDelay: overrideConfig?.retryDelay ?? DEFAULT_WIREFLOW_CONFIG.retryDelay,
+      autoConnect: overrideConfig?.autoConnect ?? DEFAULT_WIREFLOW_CONFIG.autoConnect,
+      retryOnDisconnect: overrideConfig?.retryOnDisconnect ?? DEFAULT_WIREFLOW_CONFIG.retryOnDisconnect
+    };
+  }
+  /**
+   * Assigns an optional global default WireFlowManager instance.
+   */
+  static setDefault(manager) {
+    _WireFlowManager.defaultInstance = manager;
+  }
+  /**
+   * Gets the current global default WireFlowManager instance, if one was set.
+   */
+  static getDefault() {
+    return _WireFlowManager.defaultInstance;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_WIREFLOW_CONFIG,
+  RetryManager,
+  WireFlowManager,
+  defaultConfig
+});

package/dist/index.mjs

@@ -0,0 +1,214 @@
+// src/types/index.ts
+var defaultConfig = Object.freeze({
+  autoConnect: true,
+  retryOnDisconnect: true,
+  retryAttempts: 5,
+  retryDelay: 3e3
+});
+var DEFAULT_WIREFLOW_CONFIG = defaultConfig;
+
+// src/retry/RetryManager.ts
+var RetryManager = class {
+  _maxAttempts;
+  _delay;
+  _currentAttempt = 0;
+  _timer = null;
+  _onRetryAttempt;
+  _onExhausted;
+  constructor(options = {}) {
+    this._maxAttempts = Math.max(0, options.retryAttempts ?? DEFAULT_WIREFLOW_CONFIG.retryAttempts);
+    this._delay = Math.max(0, options.retryDelay ?? DEFAULT_WIREFLOW_CONFIG.retryDelay);
+    this._onRetryAttempt = options.onRetryAttempt;
+    this._onExhausted = options.onExhausted;
+  }
+  /**
+   * Number of retries executed or currently scheduled in this retry cycle.
+   */
+  get attempts() {
+    return this._currentAttempt;
+  }
+  /**
+   * Configured maximum number of retry attempts.
+   */
+  get maxAttempts() {
+    return this._maxAttempts;
+  }
+  /**
+   * Configured delay in milliseconds.
+   */
+  get delay() {
+    return this._delay;
+  }
+  /**
+   * Indicates whether a retry delay timer is currently active.
+   */
+  get isRetrying() {
+    return this._timer !== null;
+  }
+  /**
+   * Indicates whether all configured retry attempts have been used up.
+   */
+  isExhausted() {
+    return this._currentAttempt >= this._maxAttempts;
+  }
+  /**
+   * Dynamically update configuration if needed.
+   */
+  updateConfig(options) {
+    if (typeof options.retryAttempts === "number") {
+      this._maxAttempts = Math.max(0, options.retryAttempts);
+    }
+    if (typeof options.retryDelay === "number") {
+      this._delay = Math.max(0, options.retryDelay);
+    }
+    if (options.onRetryAttempt !== void 0) {
+      this._onRetryAttempt = options.onRetryAttempt;
+    }
+    if (options.onExhausted !== void 0) {
+      this._onExhausted = options.onExhausted;
+    }
+  }
+  /**
+   * Schedules the next retry execution after `retryDelay` ms.
+   * Prevents duplicate timers if a retry is already in flight.
+   * If all attempts are exhausted, triggers `onExhausted` and returns false.
+   *
+   * @param action The connection attempt function to invoke when the timer fires.
+   * @returns `true` if a retry was scheduled; `false` if already scheduled or exhausted.
+   */
+  scheduleRetry(action) {
+    if (this._timer !== null) {
+      return false;
+    }
+    if (this.isExhausted()) {
+      this._onExhausted?.();
+      return false;
+    }
+    this._currentAttempt += 1;
+    this._onRetryAttempt?.(this._currentAttempt, this._maxAttempts, this._delay);
+    this._timer = setTimeout(() => {
+      this._timer = null;
+      try {
+        const result = action();
+        if (result instanceof Promise) {
+          result.catch(() => {
+          });
+        }
+      } catch {
+      }
+    }, this._delay);
+    return true;
+  }
+  /**
+   * Cancels any pending scheduled retry timer without resetting the attempt counter.
+   */
+  cancel() {
+    if (this._timer !== null) {
+      clearTimeout(this._timer);
+      this._timer = null;
+    }
+  }
+  /**
+   * Resets the attempt counter to 0 and cancels any active retry timer.
+   * Should be called when a connection successfully connects or when manually disconnecting.
+   */
+  reset() {
+    this.cancel();
+    this._currentAttempt = 0;
+  }
+  /**
+   * Disposes of all internal timers and callbacks.
+   */
+  dispose() {
+    this.reset();
+    this._onRetryAttempt = void 0;
+    this._onExhausted = void 0;
+  }
+};
+
+// src/manager/WireFlowManager.ts
+var WireFlowManager = class _WireFlowManager {
+  static defaultInstance = null;
+  _config;
+  constructor(customConfig = {}) {
+    this._config = {
+      retryAttempts: customConfig.retryAttempts ?? DEFAULT_WIREFLOW_CONFIG.retryAttempts,
+      retryDelay: customConfig.retryDelay ?? DEFAULT_WIREFLOW_CONFIG.retryDelay,
+      autoConnect: customConfig.autoConnect ?? DEFAULT_WIREFLOW_CONFIG.autoConnect,
+      retryOnDisconnect: customConfig.retryOnDisconnect ?? DEFAULT_WIREFLOW_CONFIG.retryOnDisconnect
+    };
+  }
+  /**
+   * Retrieves the current configuration defaults held by this manager instance.
+   */
+  get config() {
+    return { ...this._config };
+  }
+  /**
+   * Updates one or more configuration defaults on this manager instance.
+   */
+  updateConfig(newConfig) {
+    if (newConfig.retryAttempts !== void 0) {
+      this._config.retryAttempts = Math.max(0, newConfig.retryAttempts);
+    }
+    if (newConfig.retryDelay !== void 0) {
+      this._config.retryDelay = Math.max(0, newConfig.retryDelay);
+    }
+    if (newConfig.autoConnect !== void 0) {
+      this._config.autoConnect = newConfig.autoConnect;
+    }
+    if (newConfig.retryOnDisconnect !== void 0) {
+      this._config.retryOnDisconnect = newConfig.retryOnDisconnect;
+    }
+  }
+  /**
+   * Resolves final configuration by merging specific options with manager defaults
+   * and base library defaults.
+   *
+   * Priority:
+   * 1. overrideConfig (hook or client specific)
+   * 2. this._config (manager instance defaults)
+   * 3. DEFAULT_WIREFLOW_CONFIG (library defaults)
+   */
+  resolveConfig(overrideConfig) {
+    return {
+      retryAttempts: overrideConfig?.retryAttempts ?? this._config.retryAttempts,
+      retryDelay: overrideConfig?.retryDelay ?? this._config.retryDelay,
+      autoConnect: overrideConfig?.autoConnect ?? this._config.autoConnect,
+      retryOnDisconnect: overrideConfig?.retryOnDisconnect ?? this._config.retryOnDisconnect
+    };
+  }
+  /**
+   * Static helper to resolve options directly against the default singleton
+   * manager (if set) or library defaults.
+   */
+  static resolve(overrideConfig) {
+    if (_WireFlowManager.defaultInstance) {
+      return _WireFlowManager.defaultInstance.resolveConfig(overrideConfig);
+    }
+    return {
+      retryAttempts: overrideConfig?.retryAttempts ?? DEFAULT_WIREFLOW_CONFIG.retryAttempts,
+      retryDelay: overrideConfig?.retryDelay ?? DEFAULT_WIREFLOW_CONFIG.retryDelay,
+      autoConnect: overrideConfig?.autoConnect ?? DEFAULT_WIREFLOW_CONFIG.autoConnect,
+      retryOnDisconnect: overrideConfig?.retryOnDisconnect ?? DEFAULT_WIREFLOW_CONFIG.retryOnDisconnect
+    };
+  }
+  /**
+   * Assigns an optional global default WireFlowManager instance.
+   */
+  static setDefault(manager) {
+    _WireFlowManager.defaultInstance = manager;
+  }
+  /**
+   * Gets the current global default WireFlowManager instance, if one was set.
+   */
+  static getDefault() {
+    return _WireFlowManager.defaultInstance;
+  }
+};
+export {
+  DEFAULT_WIREFLOW_CONFIG,
+  RetryManager,
+  WireFlowManager,
+  defaultConfig
+};

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@wireflowapp/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Core connection primitives, types, and retry management for Wireflow",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "real-time",
+    "connection",
+    "websocket",
+    "socketio",
+    "retry",
+    "reconnection"
+  ],
+  "author": "",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }