mcp-server-framework 1.0.0

package/build/errors/categories/operation.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Operation Error Classes
+ *
+ * Errors related to operation execution:
+ * - OperationError: Generic operation failures
+ * - OperationCancelledError: Request cancellation
+ *
+ * @module errors/categories/operation
+ */
+import { AppError } from "../core/index.js";
+import type { BaseErrorOptions } from "../core/index.js";
+/**
+ * Error for failed operations.
+ *
+ * Use this for operations that fail due to business logic
+ * or external factors (not validation or internal errors).
+ *
+ * @example
+ * ```typescript
+ * throw new OperationError('Failed to process request', {
+ *   operation: 'processData',
+ *   context: { dataId: '123' }
+ * });
+ *
+ * // Using factory methods
+ * throw OperationError.failed('processData', 'timeout exceeded');
+ * ```
+ */
+export declare class OperationError extends AppError {
+    /** The operation that failed */
+    readonly operation?: string | undefined;
+    constructor(message: string, options?: Omit<BaseErrorOptions, "code"> & {
+        operation?: string | undefined;
+    });
+    /**
+     * Create an OperationError for a failed operation.
+     */
+    static failed(operation: string, reason?: string): OperationError;
+    /**
+     * Create an OperationError for a timeout.
+     */
+    static timeout(operation: string, timeoutMs: number): OperationError;
+    /**
+     * Create an OperationError for an unavailable operation.
+     */
+    static unavailable(operation: string): OperationError;
+}
+/**
+ * Error thrown when an operation is cancelled.
+ *
+ * Used primarily with AbortSignal/AbortController for
+ * cancellable operations.
+ *
+ * @example
+ * ```typescript
+ * signal.addEventListener('abort', () => {
+ *   throw new OperationCancelledError('User cancelled the request', requestId);
+ * });
+ *
+ * // Check if error is cancellation
+ * if (error instanceof OperationCancelledError) {
+ *   // Handle gracefully
+ * }
+ * ```
+ */
+export declare class OperationCancelledError extends AppError {
+    /** The ID of the cancelled request */
+    readonly requestId?: string | number | undefined;
+    /** The reason for cancellation */
+    readonly cancelReason?: string | undefined;
+    constructor(message: string, requestId?: string | number, options?: Omit<BaseErrorOptions, "code"> & {
+        cancelReason?: string | undefined;
+    });
+    /**
+     * Create from a cancelled request.
+     */
+    static fromRequest(requestId: string | number, reason?: string): OperationCancelledError;
+    /**
+     * Create from an AbortSignal.
+     */
+    static fromAbortSignal(signal: AbortSignal, requestId?: string | number): OperationCancelledError;
+}
+//# sourceMappingURL=operation.d.ts.map

package/build/errors/categories/operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/operation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,QAAQ,EAAc,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,gCAAgC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG;QACxC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B;IAqBR;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc;IASjE;;OAEG;IACH,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,cAAc;IASpE;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc;CAOtD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;IACnD,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAEjD,kCAAkC;IAClC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGzC,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAC3B,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG;QACxC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC9B;IAuBR;;OAEG;IACH,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,uBAAuB;IAQxF;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,uBAAuB;CAQlG"}

package/build/errors/categories/operation.js

@@ -0,0 +1,149 @@
+/**
+ * Operation Error Classes
+ *
+ * Errors related to operation execution:
+ * - OperationError: Generic operation failures
+ * - OperationCancelledError: Request cancellation
+ *
+ * @module errors/categories/operation
+ */
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { AppError, ErrorCodes } from "../core/index.js";
+// ============================================================================
+// Operation Error
+// ============================================================================
+/**
+ * Error for failed operations.
+ *
+ * Use this for operations that fail due to business logic
+ * or external factors (not validation or internal errors).
+ *
+ * @example
+ * ```typescript
+ * throw new OperationError('Failed to process request', {
+ *   operation: 'processData',
+ *   context: { dataId: '123' }
+ * });
+ *
+ * // Using factory methods
+ * throw OperationError.failed('processData', 'timeout exceeded');
+ * ```
+ */
+export class OperationError extends AppError {
+    /** The operation that failed */
+    operation;
+    constructor(message, options = {}) {
+        super(message, {
+            code: ErrorCodes.OPERATION_ERROR,
+            statusCode: options.statusCode || 500,
+            mcpCode: ErrorCode.InternalError,
+            cause: options.cause,
+            recoveryHint: options.recoveryHint,
+            context: {
+                ...options.context,
+                operation: options.operation,
+            },
+        });
+        this.operation = options.operation;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create an OperationError for a failed operation.
+     */
+    static failed(operation, reason) {
+        const message = reason ? `Operation '${operation}' failed: ${reason}` : `Operation '${operation}' failed`;
+        return new OperationError(message, {
+            operation,
+            recoveryHint: reason ? `Operation failed: ${reason}. Please try again.` : "Please try the operation again.",
+        });
+    }
+    /**
+     * Create an OperationError for a timeout.
+     */
+    static timeout(operation, timeoutMs) {
+        return new OperationError(`Operation '${operation}' timed out after ${timeoutMs}ms`, {
+            operation,
+            statusCode: 504,
+            context: { timeoutMs },
+            recoveryHint: `Operation '${operation}' timed out after ${timeoutMs}ms. Try again or increase timeout.`,
+        });
+    }
+    /**
+     * Create an OperationError for an unavailable operation.
+     */
+    static unavailable(operation) {
+        return new OperationError(`Operation '${operation}' is currently unavailable`, {
+            operation,
+            statusCode: 503,
+            recoveryHint: `Operation '${operation}' is currently unavailable. Please try again later.`,
+        });
+    }
+}
+// ============================================================================
+// Operation Cancelled Error
+// ============================================================================
+/**
+ * Error thrown when an operation is cancelled.
+ *
+ * Used primarily with AbortSignal/AbortController for
+ * cancellable operations.
+ *
+ * @example
+ * ```typescript
+ * signal.addEventListener('abort', () => {
+ *   throw new OperationCancelledError('User cancelled the request', requestId);
+ * });
+ *
+ * // Check if error is cancellation
+ * if (error instanceof OperationCancelledError) {
+ *   // Handle gracefully
+ * }
+ * ```
+ */
+export class OperationCancelledError extends AppError {
+    /** The ID of the cancelled request */
+    requestId;
+    /** The reason for cancellation */
+    cancelReason;
+    constructor(message, requestId, options = {}) {
+        super(message, {
+            code: ErrorCodes.OPERATION_CANCELLED,
+            statusCode: 499, // Client Closed Request
+            mcpCode: ErrorCode.InternalError,
+            cause: options.cause,
+            recoveryHint: options.recoveryHint || "The operation was cancelled. You may retry if needed.",
+            context: {
+                ...options.context,
+                requestId,
+                cancelReason: options.cancelReason,
+            },
+        });
+        this.requestId = requestId;
+        this.cancelReason = options.cancelReason;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create from a cancelled request.
+     */
+    static fromRequest(requestId, reason) {
+        const message = reason ? `Request ${requestId} was cancelled: ${reason}` : `Request ${requestId} was cancelled`;
+        return new OperationCancelledError(message, requestId, {
+            cancelReason: reason,
+        });
+    }
+    /**
+     * Create from an AbortSignal.
+     */
+    static fromAbortSignal(signal, requestId) {
+        const reason = signal.reason instanceof Error ? signal.reason.message : String(signal.reason || "Aborted");
+        return new OperationCancelledError(`Operation aborted: ${reason}`, requestId, {
+            cancelReason: reason,
+            cause: signal.reason instanceof Error ? signal.reason : undefined,
+        });
+    }
+}
+//# sourceMappingURL=operation.js.map

package/build/errors/categories/operation.js.map

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

package/build/errors/categories/protocol.d.ts

@@ -0,0 +1,68 @@
+/**
+ * MCP Protocol Error
+ *
+ * Error for MCP protocol violations (invalid JSON-RPC, missing method, etc.)
+ *
+ * @module errors/categories/protocol
+ */
+import { AppError } from "../core/index.js";
+import type { BaseErrorOptions } from "../core/index.js";
+/**
+ * Error thrown for MCP protocol violations.
+ *
+ * @example
+ * ```typescript
+ * throw McpProtocolError.invalidJson();
+ * throw McpProtocolError.invalidRequest('Missing required field');
+ * ```
+ */
+export declare class McpProtocolError extends AppError {
+    /** JSON-RPC error code */
+    readonly jsonRpcCode: number;
+    constructor(message: string, jsonRpcCode?: number, options?: Omit<BaseErrorOptions, "code">);
+    /**
+     * Create a generic invalid request error.
+     */
+    static invalidRequest(reason: string): McpProtocolError;
+    /**
+     * Create a method not found error.
+     */
+    static methodNotFound(method: string): McpProtocolError;
+    /**
+     * Create an invalid params error.
+     */
+    static invalidParams(reason: string): McpProtocolError;
+    /**
+     * Create a parse error.
+     */
+    static parseError(reason: string): McpProtocolError;
+    /**
+     * Create an error for invalid JSON.
+     */
+    static invalidJson(): McpProtocolError;
+    /**
+     * Create an error for invalid JSON-RPC version.
+     */
+    static invalidJsonRpc(): McpProtocolError;
+    /**
+     * Create an error for missing method field.
+     */
+    static missingMethod(): McpProtocolError;
+    /**
+     * Create an error for invalid batch request.
+     */
+    static invalidBatch(): McpProtocolError;
+    /**
+     * Create an error for invalid content type.
+     */
+    static invalidContentType(): McpProtocolError;
+    /**
+     * Create an error for missing Accept header.
+     */
+    static missingAccept(): McpProtocolError;
+    /**
+     * Create an error for cancelled request.
+     */
+    static requestCancelled(): McpProtocolError;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/build/errors/categories/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,QAAQ,EAA4C,MAAM,kBAAkB,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC5C,0BAA0B;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAM;IAoB/F;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAMvD;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAOvD;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAMtD;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAUnD;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,gBAAgB;IAMtC;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,gBAAgB;IAMzC;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,gBAAgB;IAMxC;;OAEG;IACH,MAAM,CAAC,YAAY,IAAI,gBAAgB;IAMvC;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,gBAAgB;IAM7C;;OAEG;IACH,MAAM,CAAC,aAAa,IAAI,gBAAgB;IAMxC;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,gBAAgB;CAK5C"}

package/build/errors/categories/protocol.js

@@ -0,0 +1,135 @@
+/**
+ * MCP Protocol Error
+ *
+ * Error for MCP protocol violations (invalid JSON-RPC, missing method, etc.)
+ *
+ * @module errors/categories/protocol
+ */
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { AppError, ErrorCodes, HttpStatus, JsonRpcErrorCode } from "../core/index.js";
+// ============================================================================
+// MCP Protocol Error
+// ============================================================================
+/**
+ * Error thrown for MCP protocol violations.
+ *
+ * @example
+ * ```typescript
+ * throw McpProtocolError.invalidJson();
+ * throw McpProtocolError.invalidRequest('Missing required field');
+ * ```
+ */
+export class McpProtocolError extends AppError {
+    /** JSON-RPC error code */
+    jsonRpcCode;
+    constructor(message, jsonRpcCode, options = {}) {
+        super(message, {
+            code: ErrorCodes.INVALID_REQUEST,
+            statusCode: HttpStatus.BAD_REQUEST,
+            mcpCode: ErrorCode.InvalidRequest,
+            cause: options.cause,
+            recoveryHint: options.recoveryHint,
+            context: {
+                ...options.context,
+                jsonRpcCode: jsonRpcCode ?? JsonRpcErrorCode.INVALID_REQUEST,
+            },
+        });
+        this.jsonRpcCode = jsonRpcCode ?? JsonRpcErrorCode.INVALID_REQUEST;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Generic Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a generic invalid request error.
+     */
+    static invalidRequest(reason) {
+        return new McpProtocolError(`Invalid request: ${reason}`, JsonRpcErrorCode.INVALID_REQUEST, {
+            recoveryHint: "Check the request format and required fields.",
+        });
+    }
+    /**
+     * Create a method not found error.
+     */
+    static methodNotFound(method) {
+        return new McpProtocolError(`Method not found: ${method}`, JsonRpcErrorCode.METHOD_NOT_FOUND, {
+            context: { method },
+            recoveryHint: `The method '${method}' does not exist. Check the method name.`,
+        });
+    }
+    /**
+     * Create an invalid params error.
+     */
+    static invalidParams(reason) {
+        return new McpProtocolError(`Invalid params: ${reason}`, JsonRpcErrorCode.INVALID_PARAMS, {
+            recoveryHint: "Check the method parameters against the expected schema.",
+        });
+    }
+    /**
+     * Create a parse error.
+     */
+    static parseError(reason) {
+        return new McpProtocolError(`Parse error: ${reason}`, JsonRpcErrorCode.PARSE_ERROR, {
+            recoveryHint: "Ensure the request body contains valid JSON syntax.",
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Specific Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create an error for invalid JSON.
+     */
+    static invalidJson() {
+        return new McpProtocolError("Invalid JSON", JsonRpcErrorCode.PARSE_ERROR, {
+            recoveryHint: "Ensure the request body contains valid JSON syntax.",
+        });
+    }
+    /**
+     * Create an error for invalid JSON-RPC version.
+     */
+    static invalidJsonRpc() {
+        return new McpProtocolError("Invalid JSON-RPC version", JsonRpcErrorCode.INVALID_REQUEST, {
+            recoveryHint: 'Ensure the request includes "jsonrpc": "2.0" field.',
+        });
+    }
+    /**
+     * Create an error for missing method field.
+     */
+    static missingMethod() {
+        return new McpProtocolError("Missing method field", JsonRpcErrorCode.INVALID_REQUEST, {
+            recoveryHint: 'Include a "method" field in the JSON-RPC request.',
+        });
+    }
+    /**
+     * Create an error for invalid batch request.
+     */
+    static invalidBatch() {
+        return new McpProtocolError("Invalid batch request: array must not be empty", JsonRpcErrorCode.INVALID_REQUEST, {
+            recoveryHint: "Batch requests must be a non-empty JSON array.",
+        });
+    }
+    /**
+     * Create an error for invalid content type.
+     */
+    static invalidContentType() {
+        return new McpProtocolError("Content-Type must be application/json", JsonRpcErrorCode.INVALID_REQUEST, {
+            recoveryHint: 'Set Content-Type header to "application/json".',
+        });
+    }
+    /**
+     * Create an error for missing Accept header.
+     */
+    static missingAccept() {
+        return new McpProtocolError("Missing Accept header", JsonRpcErrorCode.INVALID_REQUEST, {
+            recoveryHint: "Include an Accept header with supported content types.",
+        });
+    }
+    /**
+     * Create an error for cancelled request.
+     */
+    static requestCancelled() {
+        return new McpProtocolError("Request was cancelled", JsonRpcErrorCode.REQUEST_CANCELLED, {
+            recoveryHint: "The request was cancelled. Retry the operation if needed.",
+        });
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/build/errors/categories/protocol.js.map

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

package/build/errors/categories/session.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Session Error
+ *
+ * Error for MCP session management issues (not found, expired, limit reached).
+ *
+ * @module errors/categories/session
+ */
+import { AppError } from "../core/index.js";
+import type { BaseErrorOptions } from "../core/index.js";
+/**
+ * Error thrown for session management issues.
+ *
+ * @example
+ * ```typescript
+ * throw SessionError.required();
+ * throw SessionError.sessionNotFound('sess-123');
+ * ```
+ */
+export declare class SessionError extends AppError {
+    /** The session ID if applicable */
+    readonly sessionId?: string | undefined;
+    constructor(message: string, options?: Omit<BaseErrorOptions, "code"> & {
+        sessionId?: string | undefined;
+    });
+    /**
+     * Create an error for missing session ID.
+     */
+    static required(): SessionError;
+    /**
+     * Create an error for session not found (with ID).
+     */
+    static sessionNotFound(sessionId: string): SessionError;
+    /**
+     * Create an error for expired session.
+     */
+    static expired(): SessionError;
+    /**
+     * Create an error for expired session (with ID).
+     */
+    static sessionExpired(sessionId: string): SessionError;
+    /**
+     * Create an error for session limit reached.
+     */
+    static sessionLimitReached(maxSessions: number): SessionError;
+    /**
+     * Create an error for invalid session state.
+     */
+    static invalidState(sessionId: string, currentState: string, expectedState: string): SessionError;
+}
+//# sourceMappingURL=session.d.ts.map

package/build/errors/categories/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/errors/categories/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,QAAQ,EAA0B,MAAM,kBAAkB,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAMzD;;;;;;;;GAQG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IACxC,mCAAmC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;gBAGtC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,GAAG;QACxC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KAC3B;IAqBR;;OAEG;IACH,MAAM,CAAC,QAAQ,IAAI,YAAY;IAM/B;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAOvD;;OAEG;IACH,MAAM,CAAC,OAAO,IAAI,YAAY;IAM9B;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY;IAOtD;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY;IAQ7D;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,YAAY;CAUlG"}

package/build/errors/categories/session.js

@@ -0,0 +1,97 @@
+/**
+ * Session Error
+ *
+ * Error for MCP session management issues (not found, expired, limit reached).
+ *
+ * @module errors/categories/session
+ */
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { AppError, ErrorCodes, HttpStatus } from "../core/index.js";
+// ============================================================================
+// Session Error
+// ============================================================================
+/**
+ * Error thrown for session management issues.
+ *
+ * @example
+ * ```typescript
+ * throw SessionError.required();
+ * throw SessionError.sessionNotFound('sess-123');
+ * ```
+ */
+export class SessionError extends AppError {
+    /** The session ID if applicable */
+    sessionId;
+    constructor(message, options = {}) {
+        super(message, {
+            code: ErrorCodes.INVALID_REQUEST,
+            statusCode: options.statusCode ?? HttpStatus.BAD_REQUEST,
+            mcpCode: ErrorCode.InvalidRequest,
+            cause: options.cause,
+            context: {
+                ...options.context,
+                sessionId: options.sessionId,
+            },
+            recoveryHint: options.recoveryHint,
+        });
+        this.sessionId = options.sessionId;
+    }
+    // ─────────────────────────────────────────────────────────────────────────
+    // Factory Methods
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Create an error for missing session ID.
+     */
+    static required() {
+        return new SessionError("Mcp-Session-Id header required", {
+            recoveryHint: "Include the Mcp-Session-Id header in your request.",
+        });
+    }
+    /**
+     * Create an error for session not found (with ID).
+     */
+    static sessionNotFound(sessionId) {
+        return new SessionError(`Session '${sessionId}' not found`, {
+            sessionId,
+            recoveryHint: "Start a new session by connecting to the SSE endpoint.",
+        });
+    }
+    /**
+     * Create an error for expired session.
+     */
+    static expired() {
+        return new SessionError("Session has expired. Please re-initialize.", {
+            recoveryHint: "Your session has expired. Reconnect to establish a new session.",
+        });
+    }
+    /**
+     * Create an error for expired session (with ID).
+     */
+    static sessionExpired(sessionId) {
+        return new SessionError(`Session '${sessionId}' has expired`, {
+            sessionId,
+            recoveryHint: "Your session has expired. Reconnect to establish a new session.",
+        });
+    }
+    /**
+     * Create an error for session limit reached.
+     */
+    static sessionLimitReached(maxSessions) {
+        return new SessionError(`Session limit reached: maximum ${maxSessions} sessions allowed`, {
+            statusCode: HttpStatus.SERVICE_UNAVAILABLE,
+            context: { maxSessions },
+            recoveryHint: "Wait a moment and try again, or close unused sessions.",
+        });
+    }
+    /**
+     * Create an error for invalid session state.
+     */
+    static invalidState(sessionId, currentState, expectedState) {
+        return new SessionError(`Session '${sessionId}' is in invalid state '${currentState}', expected '${expectedState}'`, {
+            sessionId,
+            context: { currentState, expectedState },
+            recoveryHint: `Session is in '${currentState}' state but needs to be '${expectedState}'.`,
+        });
+    }
+}
+//# sourceMappingURL=session.js.map

package/build/errors/categories/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../../src/errors/categories/session.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGpE,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAa,SAAQ,QAAQ;IACxC,mCAAmC;IAC1B,SAAS,CAAsB;IAExC,YACE,OAAe,EACf,UAEI,EAAE;QAEN,KAAK,CAAC,OAAO,EAAE;YACb,IAAI,EAAE,UAAU,CAAC,eAAe;YAChC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,UAAU,CAAC,WAAW;YACxD,OAAO,EAAE,SAAS,CAAC,cAAc;YACjC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE;gBACP,GAAG,OAAO,CAAC,OAAO;gBAClB,SAAS,EAAE,OAAO,CAAC,SAAS;aAC7B;YACD,YAAY,EAAE,OAAO,CAAC,YAAY;SACnC,CAAC,CAAC;QAEH,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;IAED,4EAA4E;IAC5E,kBAAkB;IAClB,4EAA4E;IAE5E;;OAEG;IACH,MAAM,CAAC,QAAQ;QACb,OAAO,IAAI,YAAY,CAAC,gCAAgC,EAAE;YACxD,YAAY,EAAE,oDAAoD;SACnE,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,eAAe,CAAC,SAAiB;QACtC,OAAO,IAAI,YAAY,CAAC,YAAY,SAAS,aAAa,EAAE;YAC1D,SAAS;YACT,YAAY,EAAE,wDAAwD;SACvE,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,OAAO;QACZ,OAAO,IAAI,YAAY,CAAC,4CAA4C,EAAE;YACpE,YAAY,EAAE,iEAAiE;SAChF,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,SAAiB;QACrC,OAAO,IAAI,YAAY,CAAC,YAAY,SAAS,eAAe,EAAE;YAC5D,SAAS;YACT,YAAY,EAAE,iEAAiE;SAChF,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,WAAmB;QAC5C,OAAO,IAAI,YAAY,CAAC,kCAAkC,WAAW,mBAAmB,EAAE;YACxF,UAAU,EAAE,UAAU,CAAC,mBAAmB;YAC1C,OAAO,EAAE,EAAE,WAAW,EAAE;YACxB,YAAY,EAAE,wDAAwD;SACvE,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,SAAiB,EAAE,YAAoB,EAAE,aAAqB;QAChF,OAAO,IAAI,YAAY,CACrB,YAAY,SAAS,0BAA0B,YAAY,gBAAgB,aAAa,GAAG,EAC3F;YACE,SAAS;YACT,OAAO,EAAE,EAAE,YAAY,EAAE,aAAa,EAAE;YACxC,YAAY,EAAE,kBAAkB,YAAY,4BAA4B,aAAa,IAAI;SAC1F,CACF,CAAC;IACJ,CAAC;CACF"}