mcp-server-framework 1.0.0

package/build/connection/core/base.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Connection Error Base Classes
+ *
+ * Provides connection-specific error handling that extends the framework's AppError.
+ * Follows the same pattern as session/core/base.ts for consistency.
+ *
+ * @module connection/core/base
+ */
+import { ErrorCode as McpErrorCode } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Connection-specific error codes.
+ *
+ * These codes are local to the connection module and extend the framework's
+ * error system without polluting global error definitions.
+ */
+export declare const ConnectionErrorCodes: {
+    /** Connection to API server failed */
+    readonly CONNECTION_FAILED: "CONNECTION_FAILED";
+    /** API server is unreachable */
+    readonly SERVER_UNREACHABLE: "SERVER_UNREACHABLE";
+    /** Health check failed */
+    readonly HEALTH_CHECK_FAILED: "HEALTH_CHECK_FAILED";
+    /** Connection timeout */
+    readonly CONNECTION_TIMEOUT: "CONNECTION_TIMEOUT";
+    /** Invalid connection state transition */
+    readonly INVALID_STATE_TRANSITION: "INVALID_STATE_TRANSITION";
+    /** Client not configured */
+    readonly CLIENT_NOT_CONFIGURED: "CLIENT_NOT_CONFIGURED";
+    /** Request cancellation failed */
+    readonly CANCELLATION_FAILED: "CANCELLATION_FAILED";
+    /** Progress reporting failed */
+    readonly PROGRESS_FAILED: "PROGRESS_FAILED";
+};
+export type ConnectionErrorCode = (typeof ConnectionErrorCodes)[keyof typeof ConnectionErrorCodes];
+/**
+ * Gets the MCP error code for a connection error code.
+ */
+export declare function getMcpCodeForConnectionError(code: ConnectionErrorCode): McpErrorCode;
+/**
+ * Gets the HTTP status code for a connection error code.
+ */
+export declare function getHttpStatusForConnectionError(code: ConnectionErrorCode): number;
+//# sourceMappingURL=base.d.ts.map

package/build/connection/core/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/connection/core/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,IAAI,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAO/E;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;IAC/B,sCAAsC;;IAEtC,gCAAgC;;IAEhC,0BAA0B;;IAE1B,yBAAyB;;IAEzB,0CAA0C;;IAE1C,4BAA4B;;IAE5B,kCAAkC;;IAElC,gCAAgC;;CAExB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAsCnG;;GAEG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,mBAAmB,GAAG,YAAY,CAEpF;AAED;;GAEG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAEjF"}

package/build/connection/core/base.js

@@ -0,0 +1,82 @@
+/**
+ * Connection Error Base Classes
+ *
+ * Provides connection-specific error handling that extends the framework's AppError.
+ * Follows the same pattern as session/core/base.ts for consistency.
+ *
+ * @module connection/core/base
+ */
+import { ErrorCode as McpErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { HttpStatus } from "../../errors/index.js";
+// ============================================================================
+// Connection Error Codes
+// ============================================================================
+/**
+ * Connection-specific error codes.
+ *
+ * These codes are local to the connection module and extend the framework's
+ * error system without polluting global error definitions.
+ */
+export const ConnectionErrorCodes = {
+    /** Connection to API server failed */
+    CONNECTION_FAILED: "CONNECTION_FAILED",
+    /** API server is unreachable */
+    SERVER_UNREACHABLE: "SERVER_UNREACHABLE",
+    /** Health check failed */
+    HEALTH_CHECK_FAILED: "HEALTH_CHECK_FAILED",
+    /** Connection timeout */
+    CONNECTION_TIMEOUT: "CONNECTION_TIMEOUT",
+    /** Invalid connection state transition */
+    INVALID_STATE_TRANSITION: "INVALID_STATE_TRANSITION",
+    /** Client not configured */
+    CLIENT_NOT_CONFIGURED: "CLIENT_NOT_CONFIGURED",
+    /** Request cancellation failed */
+    CANCELLATION_FAILED: "CANCELLATION_FAILED",
+    /** Progress reporting failed */
+    PROGRESS_FAILED: "PROGRESS_FAILED",
+};
+// ============================================================================
+// Error Code Mappings
+// ============================================================================
+/**
+ * Maps connection error codes to MCP error codes.
+ */
+const connectionErrorToMcpCode = {
+    [ConnectionErrorCodes.CONNECTION_FAILED]: McpErrorCode.InternalError,
+    [ConnectionErrorCodes.SERVER_UNREACHABLE]: McpErrorCode.InternalError,
+    [ConnectionErrorCodes.HEALTH_CHECK_FAILED]: McpErrorCode.InternalError,
+    [ConnectionErrorCodes.CONNECTION_TIMEOUT]: McpErrorCode.InternalError,
+    [ConnectionErrorCodes.INVALID_STATE_TRANSITION]: McpErrorCode.InternalError,
+    [ConnectionErrorCodes.CLIENT_NOT_CONFIGURED]: McpErrorCode.InvalidRequest,
+    [ConnectionErrorCodes.CANCELLATION_FAILED]: McpErrorCode.InternalError,
+    [ConnectionErrorCodes.PROGRESS_FAILED]: McpErrorCode.InternalError,
+};
+/**
+ * Maps connection error codes to HTTP status codes.
+ */
+const connectionErrorToHttpStatus = {
+    [ConnectionErrorCodes.CONNECTION_FAILED]: HttpStatus.SERVICE_UNAVAILABLE,
+    [ConnectionErrorCodes.SERVER_UNREACHABLE]: HttpStatus.BAD_GATEWAY,
+    [ConnectionErrorCodes.HEALTH_CHECK_FAILED]: HttpStatus.SERVICE_UNAVAILABLE,
+    [ConnectionErrorCodes.CONNECTION_TIMEOUT]: HttpStatus.GATEWAY_TIMEOUT,
+    [ConnectionErrorCodes.INVALID_STATE_TRANSITION]: HttpStatus.CONFLICT,
+    [ConnectionErrorCodes.CLIENT_NOT_CONFIGURED]: HttpStatus.PRECONDITION_REQUIRED,
+    [ConnectionErrorCodes.CANCELLATION_FAILED]: HttpStatus.INTERNAL_SERVER_ERROR,
+    [ConnectionErrorCodes.PROGRESS_FAILED]: HttpStatus.INTERNAL_SERVER_ERROR,
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Gets the MCP error code for a connection error code.
+ */
+export function getMcpCodeForConnectionError(code) {
+    return connectionErrorToMcpCode[code] ?? McpErrorCode.InternalError;
+}
+/**
+ * Gets the HTTP status code for a connection error code.
+ */
+export function getHttpStatusForConnectionError(code) {
+    return connectionErrorToHttpStatus[code] ?? HttpStatus.INTERNAL_SERVER_ERROR;
+}
+//# sourceMappingURL=base.js.map

package/build/connection/core/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/connection/core/base.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,IAAI,YAAY,EAAE,MAAM,oCAAoC,CAAC;AAC/E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,sCAAsC;IACtC,iBAAiB,EAAE,mBAAmB;IACtC,gCAAgC;IAChC,kBAAkB,EAAE,oBAAoB;IACxC,0BAA0B;IAC1B,mBAAmB,EAAE,qBAAqB;IAC1C,yBAAyB;IACzB,kBAAkB,EAAE,oBAAoB;IACxC,0CAA0C;IAC1C,wBAAwB,EAAE,0BAA0B;IACpD,4BAA4B;IAC5B,qBAAqB,EAAE,uBAAuB;IAC9C,kCAAkC;IAClC,mBAAmB,EAAE,qBAAqB;IAC1C,gCAAgC;IAChC,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAIX,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,wBAAwB,GAA8C;IAC1E,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,YAAY,CAAC,aAAa;IACpE,CAAC,oBAAoB,CAAC,kBAAkB,CAAC,EAAE,YAAY,CAAC,aAAa;IACrE,CAAC,oBAAoB,CAAC,mBAAmB,CAAC,EAAE,YAAY,CAAC,aAAa;IACtE,CAAC,oBAAoB,CAAC,kBAAkB,CAAC,EAAE,YAAY,CAAC,aAAa;IACrE,CAAC,oBAAoB,CAAC,wBAAwB,CAAC,EAAE,YAAY,CAAC,aAAa;IAC3E,CAAC,oBAAoB,CAAC,qBAAqB,CAAC,EAAE,YAAY,CAAC,cAAc;IACzE,CAAC,oBAAoB,CAAC,mBAAmB,CAAC,EAAE,YAAY,CAAC,aAAa;IACtE,CAAC,oBAAoB,CAAC,eAAe,CAAC,EAAE,YAAY,CAAC,aAAa;CACnE,CAAC;AAEF;;GAEG;AACH,MAAM,2BAA2B,GAAwC;IACvE,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAAE,UAAU,CAAC,mBAAmB;IACxE,CAAC,oBAAoB,CAAC,kBAAkB,CAAC,EAAE,UAAU,CAAC,WAAW;IACjE,CAAC,oBAAoB,CAAC,mBAAmB,CAAC,EAAE,UAAU,CAAC,mBAAmB;IAC1E,CAAC,oBAAoB,CAAC,kBAAkB,CAAC,EAAE,UAAU,CAAC,eAAe;IACrE,CAAC,oBAAoB,CAAC,wBAAwB,CAAC,EAAE,UAAU,CAAC,QAAQ;IACpE,CAAC,oBAAoB,CAAC,qBAAqB,CAAC,EAAE,UAAU,CAAC,qBAAqB;IAC9E,CAAC,oBAAoB,CAAC,mBAAmB,CAAC,EAAE,UAAU,CAAC,qBAAqB;IAC5E,CAAC,oBAAoB,CAAC,eAAe,CAAC,EAAE,UAAU,CAAC,qBAAqB;CACzE,CAAC;AAEF,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAAyB;IACpE,OAAO,wBAAwB,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,aAAa,CAAC;AACtE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,+BAA+B,CAAC,IAAyB;IACvE,OAAO,2BAA2B,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,qBAAqB,CAAC;AAC/E,CAAC"}

package/build/connection/core/constants.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Connection Module Constants
+ *
+ * Centralized constants for the connection module including:
+ * - Configuration values
+ * - Log component identifiers
+ * - MCP specification references
+ * - Log messages
+ *
+ * @module connection/core/constants
+ */
+/**
+ * Connection state configuration constants.
+ */
+export declare const CONNECTION_STATE_CONFIG: {
+    /**
+     * Maximum number of state transitions to keep in history.
+     * Uses circular buffer for O(1) operations.
+     */
+    readonly MAX_HISTORY_SIZE: 10;
+    /**
+     * Default timeout for health checks in milliseconds.
+     */
+    readonly HEALTH_CHECK_TIMEOUT_MS: 10000;
+};
+/**
+ * Default configuration for auto-reconnect.
+ * Modeled after the SDK's StreamableHTTPReconnectionOptions pattern.
+ */
+export declare const RECONNECT_DEFAULTS: {
+    /** Maximum number of reconnect attempts before giving up. */
+    readonly MAX_RETRIES: 5;
+    /** Initial delay before the first reconnect attempt (ms). */
+    readonly INITIAL_DELAY_MS: 1000;
+    /** Maximum delay between reconnect attempts (ms). */
+    readonly MAX_DELAY_MS: 30000;
+    /** Exponential backoff multiplier. */
+    readonly BACKOFF_MULTIPLIER: 1.5;
+};
+/**
+ * Valid state transitions for the connection state machine.
+ *
+ * Enforces the documented state graph:
+ * ```
+ * disconnected ──▶ connecting ──▶ connected
+ *      ▲                │              │
+ *      │                ▼              ▼
+ *      └──────────── error ◀──────────┘
+ * ```
+ *
+ * Additional transitions allowed for practical use:
+ * - `connected → disconnected` (explicit disconnect)
+ * - `error → disconnected` (reset)
+ */
+export declare const VALID_STATE_TRANSITIONS: Readonly<Record<string, readonly string[]>>;
+/**
+ * Logger component identifiers for the connection module.
+ * Used for consistent log categorization.
+ */
+export declare const CONNECTION_LOG_COMPONENTS: {
+    /** Connection state manager component */
+    readonly CONNECTION_STATE: "ConnectionStateManager";
+    /** Client initializer component */
+    readonly CLIENT_INITIALIZER: "ClientInitializer";
+};
+/**
+ * MCP specification URLs for documentation and compliance references.
+ */
+export declare const CONNECTION_MCP_SPEC: {
+    /** MCP specification version */
+    readonly VERSION: "2025-11-25";
+    /** Base URL for MCP specification */
+    readonly BASE_URL: "https://spec.modelcontextprotocol.io/specification/2025-11-25";
+    /** Progress notifications specification */
+    readonly PROGRESS_URL: "https://spec.modelcontextprotocol.io/specification/2025-11-25/server/utilities/progress/";
+    /** Cancellation specification */
+    readonly CANCELLATION_URL: "https://spec.modelcontextprotocol.io/specification/2025-11-25/basic/cancellation/";
+};
+/**
+ * Centralized log messages for connection state management.
+ */
+export declare const ConnectionStateLogMessages: {
+    readonly STATE_CHANGE: "State transition: %s → %s";
+    readonly CONNECTING: "Initiating connection to API server";
+    readonly CONNECTED: "Successfully connected to API server";
+    readonly DISCONNECTED: "Disconnected from API server";
+    readonly ERROR_STATE: "Connection error: %s";
+    readonly HEALTH_CHECK_START: "Starting health check";
+    readonly HEALTH_CHECK_SUCCESS: "Health check passed";
+    readonly HEALTH_CHECK_FAILED: "Health check failed: %s";
+    readonly HEALTH_CHECK_SKIPPED: "Health check skipped";
+    readonly HEALTH_CHECK_TIMEOUT: "Health check timed out after %dms";
+    readonly INVALID_TRANSITION: "Invalid state transition: %s → %s (allowed from %s: %s)";
+    readonly CLIENT_DISCONNECT_ERROR: "Client disconnect failed (ignored): %s";
+    readonly LISTENER_ADDED: "State change listener added";
+    readonly LISTENER_REMOVED: "State change listener removed";
+    readonly LISTENER_ERROR: "Listener threw error: %s";
+    readonly LISTENERS_CLEARED: "All listeners cleared";
+    readonly RESET: "Connection state manager reset to initial state";
+    readonly RECONNECT_ENABLED: "Auto-reconnect enabled (maxRetries=%d, initialDelay=%dms, maxDelay=%dms)";
+    readonly RECONNECT_DISABLED: "Auto-reconnect disabled";
+    readonly RECONNECT_ATTEMPT: "Reconnect attempt %d/%d in %dms";
+    readonly RECONNECT_SUCCESS: "Reconnect succeeded after %d attempt(s)";
+    readonly RECONNECT_FAILED: "Reconnect attempt %d/%d failed: %s";
+    readonly RECONNECT_EXHAUSTED: "All %d reconnect attempts exhausted — staying in error state";
+    readonly RECONNECT_ABORTED: "Reconnect aborted";
+};
+/**
+ * Centralized log messages for client initialization.
+ */
+export declare const ClientInitializerLogMessages: {
+    readonly INIT_START: "Initializing API client from environment variables";
+    readonly INIT_SUCCESS: "Client initialized successfully using %s";
+    readonly INIT_FAILED: "Client initialization failed: %s";
+    readonly CONFIG_MISSING: "Missing required configuration";
+    readonly CONFIG_URL_MISSING: "API URL environment variable not set";
+    readonly CONFIG_AUTH_MISSING: "No authentication method configured (need API_KEY or USERNAME/PASSWORD)";
+    readonly AUTH_API_KEY: "Using API key authentication";
+    readonly AUTH_CREDENTIALS: "Using username/password authentication";
+};
+//# sourceMappingURL=constants.d.ts.map

package/build/connection/core/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/connection/core/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH;;GAEG;AACH,eAAO,MAAM,uBAAuB;IAClC;;;OAGG;;IAGH;;OAEG;;CAEK,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,kBAAkB;IAC7B,6DAA6D;;IAE7D,6DAA6D;;IAE7D,qDAAqD;;IAErD,sCAAsC;;CAE9B,CAAC;AAMX;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAKtE,CAAC;AAMX;;;GAGG;AACH,eAAO,MAAM,yBAAyB;IACpC,yCAAyC;;IAEzC,mCAAmC;;CAE3B,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,mBAAmB;IAC9B,gCAAgC;;IAEhC,qCAAqC;;IAErC,2CAA2C;;IAE3C,iCAAiC;;CAEzB,CAAC;AAMX;;GAEG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;CAsC7B,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,4BAA4B;;;;;;;;;CAc/B,CAAC"}

package/build/connection/core/constants.js

@@ -0,0 +1,151 @@
+/**
+ * Connection Module Constants
+ *
+ * Centralized constants for the connection module including:
+ * - Configuration values
+ * - Log component identifiers
+ * - MCP specification references
+ * - Log messages
+ *
+ * @module connection/core/constants
+ */
+// ============================================================================
+// Configuration Constants
+// ============================================================================
+/**
+ * Connection state configuration constants.
+ */
+export const CONNECTION_STATE_CONFIG = {
+    /**
+     * Maximum number of state transitions to keep in history.
+     * Uses circular buffer for O(1) operations.
+     */
+    MAX_HISTORY_SIZE: 10,
+    /**
+     * Default timeout for health checks in milliseconds.
+     */
+    HEALTH_CHECK_TIMEOUT_MS: 10_000,
+};
+/**
+ * Default configuration for auto-reconnect.
+ * Modeled after the SDK's StreamableHTTPReconnectionOptions pattern.
+ */
+export const RECONNECT_DEFAULTS = {
+    /** Maximum number of reconnect attempts before giving up. */
+    MAX_RETRIES: 5,
+    /** Initial delay before the first reconnect attempt (ms). */
+    INITIAL_DELAY_MS: 1_000,
+    /** Maximum delay between reconnect attempts (ms). */
+    MAX_DELAY_MS: 30_000,
+    /** Exponential backoff multiplier. */
+    BACKOFF_MULTIPLIER: 1.5,
+};
+// ============================================================================
+// State Machine Transition Rules
+// ============================================================================
+/**
+ * Valid state transitions for the connection state machine.
+ *
+ * Enforces the documented state graph:
+ * ```
+ * disconnected ──▶ connecting ──▶ connected
+ *      ▲                │              │
+ *      │                ▼              ▼
+ *      └──────────── error ◀──────────┘
+ * ```
+ *
+ * Additional transitions allowed for practical use:
+ * - `connected → disconnected` (explicit disconnect)
+ * - `error → disconnected` (reset)
+ */
+export const VALID_STATE_TRANSITIONS = {
+    disconnected: ["connecting"],
+    connecting: ["connected", "error", "disconnected"],
+    connected: ["connecting", "disconnected", "error"],
+    error: ["connecting", "disconnected"],
+};
+// ============================================================================
+// Log Component Identifiers
+// ============================================================================
+/**
+ * Logger component identifiers for the connection module.
+ * Used for consistent log categorization.
+ */
+export const CONNECTION_LOG_COMPONENTS = {
+    /** Connection state manager component */
+    CONNECTION_STATE: "ConnectionStateManager",
+    /** Client initializer component */
+    CLIENT_INITIALIZER: "ClientInitializer",
+};
+// ============================================================================
+// MCP Specification References
+// ============================================================================
+/**
+ * MCP specification URLs for documentation and compliance references.
+ */
+export const CONNECTION_MCP_SPEC = {
+    /** MCP specification version */
+    VERSION: "2025-11-25",
+    /** Base URL for MCP specification */
+    BASE_URL: "https://spec.modelcontextprotocol.io/specification/2025-11-25",
+    /** Progress notifications specification */
+    PROGRESS_URL: "https://spec.modelcontextprotocol.io/specification/2025-11-25/server/utilities/progress/",
+    /** Cancellation specification */
+    CANCELLATION_URL: "https://spec.modelcontextprotocol.io/specification/2025-11-25/basic/cancellation/",
+};
+// ============================================================================
+// Log Messages
+// ============================================================================
+/**
+ * Centralized log messages for connection state management.
+ */
+export const ConnectionStateLogMessages = {
+    // State transitions
+    STATE_CHANGE: "State transition: %s → %s",
+    CONNECTING: "Initiating connection to API server",
+    CONNECTED: "Successfully connected to API server",
+    DISCONNECTED: "Disconnected from API server",
+    ERROR_STATE: "Connection error: %s",
+    // Health check
+    HEALTH_CHECK_START: "Starting health check",
+    HEALTH_CHECK_SUCCESS: "Health check passed",
+    HEALTH_CHECK_FAILED: "Health check failed: %s",
+    HEALTH_CHECK_SKIPPED: "Health check skipped",
+    HEALTH_CHECK_TIMEOUT: "Health check timed out after %dms",
+    // State machine
+    INVALID_TRANSITION: "Invalid state transition: %s → %s (allowed from %s: %s)",
+    // Client lifecycle
+    CLIENT_DISCONNECT_ERROR: "Client disconnect failed (ignored): %s",
+    // Listeners
+    LISTENER_ADDED: "State change listener added",
+    LISTENER_REMOVED: "State change listener removed",
+    LISTENER_ERROR: "Listener threw error: %s",
+    LISTENERS_CLEARED: "All listeners cleared",
+    // Reset
+    RESET: "Connection state manager reset to initial state",
+    // Auto-Reconnect
+    RECONNECT_ENABLED: "Auto-reconnect enabled (maxRetries=%d, initialDelay=%dms, maxDelay=%dms)",
+    RECONNECT_DISABLED: "Auto-reconnect disabled",
+    RECONNECT_ATTEMPT: "Reconnect attempt %d/%d in %dms",
+    RECONNECT_SUCCESS: "Reconnect succeeded after %d attempt(s)",
+    RECONNECT_FAILED: "Reconnect attempt %d/%d failed: %s",
+    RECONNECT_EXHAUSTED: "All %d reconnect attempts exhausted — staying in error state",
+    RECONNECT_ABORTED: "Reconnect aborted",
+};
+/**
+ * Centralized log messages for client initialization.
+ */
+export const ClientInitializerLogMessages = {
+    // Initialization
+    INIT_START: "Initializing API client from environment variables",
+    INIT_SUCCESS: "Client initialized successfully using %s",
+    INIT_FAILED: "Client initialization failed: %s",
+    // Configuration
+    CONFIG_MISSING: "Missing required configuration",
+    CONFIG_URL_MISSING: "API URL environment variable not set",
+    CONFIG_AUTH_MISSING: "No authentication method configured (need API_KEY or USERNAME/PASSWORD)",
+    // Authentication
+    AUTH_API_KEY: "Using API key authentication",
+    AUTH_CREDENTIALS: "Using username/password authentication",
+};
+//# sourceMappingURL=constants.js.map

package/build/connection/core/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/connection/core/constants.ts"],"names":[],"mappings":"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"}

package/build/connection/core/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Connection Core Module
+ *
+ * Barrel export for centralized types and constants.
+ *
+ * @module connection/core
+ */
+export type { ConnectionState, ConnectionStateListener, ConnectionStateEvent, ConnectionStateStats, ConnectionTelemetry, TelemetrySpan, } from "./types.js";
+export { CONNECTION_STATES, NO_OP_TELEMETRY } from "./types.js";
+export { ConnectionErrorCodes, getMcpCodeForConnectionError, getHttpStatusForConnectionError } from "./base.js";
+export type { ConnectionErrorCode } from "./base.js";
+export { CONNECTION_STATE_CONFIG, CONNECTION_LOG_COMPONENTS, CONNECTION_MCP_SPEC, RECONNECT_DEFAULTS, VALID_STATE_TRANSITIONS, ConnectionStateLogMessages, ClientInitializerLogMessages, } from "./constants.js";
+//# sourceMappingURL=index.d.ts.map

package/build/connection/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/connection/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAEV,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EAEpB,mBAAmB,EACnB,aAAa,GACd,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGhE,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAChH,YAAY,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGrD,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC"}

package/build/connection/core/index.js

@@ -0,0 +1,14 @@
+/**
+ * Connection Core Module
+ *
+ * Barrel export for centralized types and constants.
+ *
+ * @module connection/core
+ */
+// Note: ProgressData and ProgressReporter are exported from mcp/types/context.ts (canonical source)
+export { CONNECTION_STATES, NO_OP_TELEMETRY } from "./types.js";
+// Connection Error Codes & Mappings
+export { ConnectionErrorCodes, getMcpCodeForConnectionError, getHttpStatusForConnectionError } from "./base.js";
+// Constants
+export { CONNECTION_STATE_CONFIG, CONNECTION_LOG_COMPONENTS, CONNECTION_MCP_SPEC, RECONNECT_DEFAULTS, VALID_STATE_TRANSITIONS, ConnectionStateLogMessages, ClientInitializerLogMessages, } from "./constants.js";
+//# sourceMappingURL=index.js.map

package/build/connection/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/connection/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,oGAAoG;AAEpG,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEhE,oCAAoC;AACpC,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,+BAA+B,EAAE,MAAM,WAAW,CAAC;AAGhH,YAAY;AACZ,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,EACvB,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC"}

package/build/connection/core/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Connection Module Types
+ *
+ * Centralized type definitions for the connection module.
+ * Includes connection state management and request tracking types.
+ * Generic types work with any service client implementing ServiceClient.
+ *
+ * @module connection/core/types
+ */
+import type { ServiceClient } from "../types.js";
+/**
+ * Telemetry operations used by ConnectionStateManager.
+ *
+ * Abstracts tracing and metrics to avoid a direct dependency
+ * from connection/ → server/telemetry/. Callers inject the
+ * real implementation; the default is a no-op.
+ */
+export interface ConnectionTelemetry {
+    /** Wrap an async operation in a tracing span. */
+    withSpan<T>(name: string, fn: (span: TelemetrySpan) => Promise<T>): Promise<T>;
+    /** Add attributes to the current active span. */
+    addSpanAttributes(attrs: Record<string, string | number | boolean | undefined>): void;
+    /** Add a named event to the current active span. */
+    addSpanEvent(name: string, attrs?: Record<string, string | number | boolean | undefined>): void;
+    /** Record a connection state transition in metrics. */
+    recordConnectionStateChange(previousState: string, newState: string): void;
+}
+/**
+ * Minimal span interface for the telemetry abstraction.
+ * Avoids importing OpenTelemetry API types into the connection/ layer.
+ */
+export interface TelemetrySpan {
+    setAttribute(key: string, value: string | number | boolean): void;
+}
+/**
+ * No-op telemetry implementation.
+ *
+ * Used as default when no telemetry is injected. All methods are silent no-ops,
+ * which is safe because the server/telemetry module already handles the
+ * "OTEL not initialized" case the same way.
+ */
+export declare const NO_OP_TELEMETRY: ConnectionTelemetry;
+/**
+ * Possible connection states for the service client.
+ *
+ * State Machine:
+ * ```
+ * disconnected ──▶ connecting ──▶ connected
+ *      ▲                │              │
+ *      │                ▼              │
+ *      └──────────── error ◀──────────┘
+ * ```
+ */
+export type ConnectionState = "disconnected" | "connecting" | "connected" | "error";
+/**
+ * All possible connection states as a readonly array.
+ * Useful for validation and iteration.
+ */
+export declare const CONNECTION_STATES: readonly ["disconnected", "connecting", "connected", "error"];
+/**
+ * Listener function signature for connection state changes.
+ *
+ * @typeParam TService - The service client type (must implement ServiceClient)
+ * @param state - The new connection state
+ * @param client - The service client (null if not connected)
+ * @param error - Error object if state is 'error'
+ */
+export type ConnectionStateListener<TService extends ServiceClient = ServiceClient> = (state: ConnectionState, client: TService | null, error?: Error) => void;
+/**
+ * Event object representing a connection state transition.
+ * Used for history tracking and debugging.
+ *
+ * @typeParam TService - The service client type (must implement ServiceClient)
+ */
+export interface ConnectionStateEvent {
+    /** The previous connection state */
+    readonly previousState: ConnectionState;
+    /** The new (current) connection state */
+    readonly currentState: ConnectionState;
+    /** The client type identifier at the time of transition (e.g. 'my-api') */
+    readonly clientType: string | null;
+    /** Error that caused the transition (if applicable) */
+    readonly error?: Error | undefined;
+    /** Timestamp when the transition occurred */
+    readonly timestamp: Date;
+}
+/**
+ * Statistics about the connection state manager.
+ */
+export interface ConnectionStateStats {
+    /** Current connection state */
+    readonly state: ConnectionState;
+    /** Whether currently connected */
+    readonly isConnected: boolean;
+    /** Number of registered listeners */
+    readonly listenerCount: number;
+    /** Number of state transitions in history */
+    readonly historyLength: number;
+    /** Last error if any */
+    readonly lastError: Error | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/connection/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/connection/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,iDAAiD;IACjD,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAE/E,iDAAiD;IACjD,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;IAEtF,oDAAoD;IACpD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;IAEhG,uDAAuD;IACvD,2BAA2B,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5E;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;CACnE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,EAAE,mBAQ7B,CAAC;AAMF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,OAAO,CAAC;AAEpF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,+DAAgE,CAAC;AAE/F;;;;;;;GAOG;AACH,MAAM,MAAM,uBAAuB,CAAC,QAAQ,SAAS,aAAa,GAAG,aAAa,IAAI,CACpF,KAAK,EAAE,eAAe,EACtB,MAAM,EAAE,QAAQ,GAAG,IAAI,EACvB,KAAK,CAAC,EAAE,KAAK,KACV,IAAI,CAAC;AAEV;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,QAAQ,CAAC,aAAa,EAAE,eAAe,CAAC;IACxC,yCAAyC;IACzC,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,6CAA6C;IAC7C,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,kCAAkC;IAClC,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,wBAAwB;IACxB,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,IAAI,CAAC;CAClC"}

package/build/connection/core/types.js

@@ -0,0 +1,31 @@
+/**
+ * Connection Module Types
+ *
+ * Centralized type definitions for the connection module.
+ * Includes connection state management and request tracking types.
+ * Generic types work with any service client implementing ServiceClient.
+ *
+ * @module connection/core/types
+ */
+/**
+ * No-op telemetry implementation.
+ *
+ * Used as default when no telemetry is injected. All methods are silent no-ops,
+ * which is safe because the server/telemetry module already handles the
+ * "OTEL not initialized" case the same way.
+ */
+export const NO_OP_TELEMETRY = {
+    async withSpan(_name, fn) {
+        const noopSpan = { setAttribute: () => { } };
+        return fn(noopSpan);
+    },
+    addSpanAttributes: () => { },
+    addSpanEvent: () => { },
+    recordConnectionStateChange: () => { },
+};
+/**
+ * All possible connection states as a readonly array.
+ * Useful for validation and iteration.
+ */
+export const CONNECTION_STATES = ["disconnected", "connecting", "connected", "error"];
+//# sourceMappingURL=types.js.map

package/build/connection/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/connection/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAqCH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAwB;IAClD,KAAK,CAAC,QAAQ,CAAI,KAAa,EAAE,EAAuC;QACtE,MAAM,QAAQ,GAAkB,EAAE,YAAY,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,CAAC,QAAQ,CAAC,CAAC;IACtB,CAAC;IACD,iBAAiB,EAAE,GAAG,EAAE,GAAE,CAAC;IAC3B,YAAY,EAAE,GAAG,EAAE,GAAE,CAAC;IACtB,2BAA2B,EAAE,GAAG,EAAE,GAAE,CAAC;CACtC,CAAC;AAmBF;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,CAAU,CAAC"}

package/build/connection/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Connection Module
+ *
+ * Manages backend service connection state and lifecycle for the MCP framework.
+ * This module is generic and client-agnostic — it works with any ServiceClient.
+ *
+ * This module handles the connection to backend services, NOT the MCP transport layer.
+ * For transport lifecycle, see the transport-specific modules (sse/lifecycle, streamable-http/lifecycle).
+ *
+ * @module connection
+ */
+export type { HealthStatus, HealthCheckResult, ServiceClient, ServiceClientFactory } from "./types.js";
+export { isServiceClient } from "./types.js";
+export type { ConnectionState, ConnectionStateListener, ConnectionStateEvent, ConnectionStateStats, ConnectionErrorCode, ConnectionTelemetry, TelemetrySpan, } from "./core/index.js";
+export { ConnectionErrorCodes, getMcpCodeForConnectionError, getHttpStatusForConnectionError } from "./core/index.js";
+export { CONNECTION_STATES, CONNECTION_STATE_CONFIG, CONNECTION_LOG_COMPONENTS, CONNECTION_MCP_SPEC, RECONNECT_DEFAULTS, ConnectionStateLogMessages, ClientInitializerLogMessages, NO_OP_TELEMETRY, } from "./core/index.js";
+export { ConnectionStateManager } from "./connection-state.js";
+export type { ReconnectOptions, ConnectionStateOptions } from "./connection-state.js";
+//# sourceMappingURL=index.d.ts.map

package/build/connection/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/connection/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvG,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAO7C,YAAY,EAEV,eAAe,EACf,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EAEpB,mBAAmB,EAEnB,mBAAmB,EACnB,aAAa,GACd,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAAE,oBAAoB,EAAE,4BAA4B,EAAE,+BAA+B,EAAE,MAAM,iBAAiB,CAAC;AAGtH,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,0BAA0B,EAC1B,4BAA4B,EAC5B,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

package/build/connection/index.js

@@ -0,0 +1,22 @@
+/**
+ * Connection Module
+ *
+ * Manages backend service connection state and lifecycle for the MCP framework.
+ * This module is generic and client-agnostic — it works with any ServiceClient.
+ *
+ * This module handles the connection to backend services, NOT the MCP transport layer.
+ * For transport lifecycle, see the transport-specific modules (sse/lifecycle, streamable-http/lifecycle).
+ *
+ * @module connection
+ */
+export { isServiceClient } from "./types.js";
+// Note: ProgressData and ProgressReporter are exported from mcp/types/context.ts
+// Re-export error codes from core
+export { ConnectionErrorCodes, getMcpCodeForConnectionError, getHttpStatusForConnectionError } from "./core/index.js";
+// Re-export constants from core
+export { CONNECTION_STATES, CONNECTION_STATE_CONFIG, CONNECTION_LOG_COMPONENTS, CONNECTION_MCP_SPEC, RECONNECT_DEFAULTS, ConnectionStateLogMessages, ClientInitializerLogMessages, NO_OP_TELEMETRY, } from "./core/index.js";
+// ============================================================================
+// Connection State Management (generic)
+// ============================================================================
+export { ConnectionStateManager } from "./connection-state.js";
+//# sourceMappingURL=index.js.map