@kontext-dev/js-sdk 0.3.0 → 1.1.0

package/dist/errors.cjs

@@ -1,5 +1,7 @@
 'use strict';
 
+var types_js = require('@modelcontextprotocol/sdk/types.js');
+
 // src/errors.ts
 var KontextError = class extends Error {
   /** Brand field for type narrowing without instanceof */
@@ -133,12 +135,20 @@ function isNetworkError(err) {
     if (typeof causeCode === "string" && NETWORK_ERROR_CODES.has(causeCode))
       return true;
   }
+  if (err.name === "TypeError") {
+    const msg = err.message.toLowerCase();
+    if (msg === "failed to fetch" || msg === "load failed" || msg.includes("networkerror")) {
+      return true;
+    }
+  }
   return false;
 }
 function isUnauthorizedError(err) {
   const props = errorProps(err);
   if (props.statusCode === 401 || props.status === 401) return true;
+  if (props.code === 401) return true;
   if (err.name === "UnauthorizedError") return true;
+  if (err.constructor?.name === "UnauthorizedError") return true;
   if (err.message === "Unauthorized") return true;
   return false;
 }
@@ -197,6 +207,73 @@ function parseHttpError(statusCode, body) {
       });
   }
 }
+var MCP_CODE_MAP = {
+  [types_js.ErrorCode.ParseError]: { code: "kontext_mcp_parse_error" },
+  [types_js.ErrorCode.InvalidRequest]: { code: "kontext_mcp_invalid_request" },
+  [types_js.ErrorCode.MethodNotFound]: { code: "kontext_mcp_method_not_found" },
+  [types_js.ErrorCode.InvalidParams]: { code: "kontext_mcp_invalid_params" },
+  [types_js.ErrorCode.InternalError]: {
+    code: "kontext_mcp_internal_error",
+    statusCode: 500
+  },
+  [types_js.ErrorCode.RequestTimeout]: {
+    code: "kontext_mcp_session_expired",
+    statusCode: 401
+  },
+  [types_js.ErrorCode.ConnectionClosed]: { code: "kontext_mcp_session_error" }
+};
+function translateError(err) {
+  if (isKontextError(err)) return err;
+  if (!(err instanceof Error)) {
+    return new KontextError(String(err), "kontext_unknown_error");
+  }
+  const props = err;
+  if (props.code === types_js.ErrorCode.UrlElicitationRequired) {
+    const elicitations = props.elicitations ?? props.data?.elicitations;
+    const elicitation = elicitations?.[0];
+    return new IntegrationConnectionRequiredError(
+      elicitation?.integrationId ?? "unknown",
+      {
+        integrationName: elicitation?.integrationName,
+        connectUrl: elicitation?.url,
+        message: elicitation?.message,
+        cause: err
+      }
+    );
+  }
+  if (typeof props.code === "number" && props.code < 0) {
+    const entry = MCP_CODE_MAP[props.code];
+    if (entry) {
+      return new KontextError(err.message, entry.code, {
+        statusCode: entry.statusCode,
+        cause: err
+      });
+    }
+    return new KontextError(err.message, "kontext_mcp_error", {
+      cause: err,
+      meta: { mcpCode: props.code }
+    });
+  }
+  const statusCode = props.statusCode ?? props.status ?? (typeof props.code === "number" && props.code >= 400 && props.code < 600 ? props.code : void 0);
+  if (typeof statusCode === "number" && statusCode >= 400) {
+    if (statusCode === 401) {
+      return new AuthorizationRequiredError(err.message, { cause: err });
+    }
+    return new KontextError(err.message, "kontext_server_error", {
+      statusCode,
+      cause: err
+    });
+  }
+  if (isUnauthorizedError(err)) {
+    return new AuthorizationRequiredError(err.message, { cause: err });
+  }
+  if (isNetworkError(err)) {
+    return new NetworkError(err.message, { cause: err });
+  }
+  return new KontextError(err.message, "kontext_unknown_error", {
+    cause: err
+  });
+}
 
 exports.AuthorizationRequiredError = AuthorizationRequiredError;
 exports.ConfigError = ConfigError;
@@ -209,5 +286,6 @@ exports.isKontextError = isKontextError;
 exports.isNetworkError = isNetworkError;
 exports.isUnauthorizedError = isUnauthorizedError;
 exports.parseHttpError = parseHttpError;
+exports.translateError = translateError;
 //# sourceMappingURL=errors.cjs.map
 //# sourceMappingURL=errors.cjs.map

package/dist/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":"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","file":"errors.cjs","sourcesContent":["/**\n * Typed error classes for the Kontext SDK.\n *\n * Every error has a `kontext_` prefixed code, an auto-generated docsUrl,\n * and a `kontextError` brand for type narrowing without instanceof.\n *\n * @packageDocumentation\n */\n\n// ============================================================================\n// Base\n// ============================================================================\n\n/**\n * Base error class for all Kontext SDK errors.\n *\n * @example\n * ```typescript\n * import { isKontextError } from '@kontext-dev/js-sdk';\n *\n * try {\n *   await client.connect();\n * } catch (err) {\n *   if (isKontextError(err)) {\n *     console.log(err.code);    // \"kontext_authorization_required\"\n *     console.log(err.docsUrl); // \"https://docs.kontext.dev/errors/kontext_authorization_required\"\n *   }\n * }\n * ```\n */\nexport class KontextError extends Error {\n  /** Brand field for type narrowing without instanceof */\n  readonly kontextError = true as const;\n\n  /** Machine-readable error code, always prefixed with `kontext_` */\n  readonly code: string;\n\n  /** HTTP status code when applicable */\n  readonly statusCode?: number;\n\n  /** Auto-generated link to error documentation */\n  readonly docsUrl: string;\n\n  /** Server request ID for debugging / support escalation */\n  readonly requestId?: string;\n\n  /** Contextual metadata bag (integration IDs, param names, etc.) */\n  readonly meta: Record<string, unknown>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options?.cause });\n    this.name = \"KontextError\";\n    this.code = code;\n    this.statusCode = options?.statusCode;\n    this.requestId = options?.requestId;\n    this.meta = options?.meta ?? {};\n    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      statusCode: this.statusCode,\n      docsUrl: this.docsUrl,\n      requestId: this.requestId,\n      meta: Object.keys(this.meta).length > 0 ? this.meta : undefined,\n    };\n  }\n\n  override toString(): string {\n    const parts = [`[${this.code}] ${this.message}`];\n    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);\n    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);\n    return parts.join(\"\\n\");\n  }\n}\n\n// ============================================================================\n// Type guard\n// ============================================================================\n\n/**\n * Check if an error is a KontextError without instanceof.\n * Works across package versions and bundler deduplication.\n */\nexport function isKontextError(err: unknown): err is KontextError {\n  return (\n    typeof err === \"object\" &&\n    err !== null &&\n    (err as Record<string, unknown>).kontextError === true\n  );\n}\n\n// ============================================================================\n// Auth errors\n// ============================================================================\n\n/**\n * Thrown when authentication is required but no valid credentials are available.\n */\nexport class AuthorizationRequiredError extends KontextError {\n  readonly authorizationUrl?: string;\n\n  constructor(\n    message = \"Authorization required. Complete the OAuth flow to continue.\",\n    options?: {\n      authorizationUrl?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, \"kontext_authorization_required\", {\n      statusCode: 401,\n      ...options,\n    });\n    this.name = \"AuthorizationRequiredError\";\n    this.authorizationUrl = options?.authorizationUrl;\n  }\n}\n\n// ============================================================================\n// OAuth errors\n// ============================================================================\n\n/**\n * Thrown when an OAuth flow fails — state validation, token exchange,\n * missing code verifier, or provider errors.\n */\nexport class OAuthError extends KontextError {\n  readonly errorCode?: string;\n  readonly errorDescription?: string;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      errorCode?: string;\n      errorDescription?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode ?? 400,\n      ...options,\n    });\n    this.name = \"OAuthError\";\n    this.errorCode = options?.errorCode;\n    this.errorDescription = options?.errorDescription;\n  }\n}\n\n// ============================================================================\n// Integration errors\n// ============================================================================\n\n/**\n * Thrown when an integration connection is required before a tool can be used.\n */\nexport class IntegrationConnectionRequiredError extends KontextError {\n  readonly integrationId: string;\n  readonly integrationName?: string;\n  readonly connectUrl?: string;\n\n  constructor(\n    integrationId: string,\n    options?: {\n      integrationName?: string;\n      connectUrl?: string;\n      message?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(\n      options?.message ??\n        `Connection to integration \"${integrationId}\" is required. Visit the connect URL to authorize.`,\n      \"kontext_integration_connection_required\",\n      { statusCode: 403, ...options },\n    );\n    this.name = \"IntegrationConnectionRequiredError\";\n    this.integrationId = integrationId;\n    this.integrationName = options?.integrationName;\n    this.connectUrl = options?.connectUrl;\n  }\n}\n\n// ============================================================================\n// Config errors (NEW — replaces all plain Error config throws)\n// ============================================================================\n\n/**\n * Thrown when SDK configuration is invalid or missing.\n * These are deterministic errors caught at initialization time.\n */\nexport class ConfigError extends KontextError {\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, options);\n    this.name = \"ConfigError\";\n  }\n}\n\n// ============================================================================\n// Network errors\n// ============================================================================\n\n/**\n * Thrown when there is a network or connection error.\n */\nexport class NetworkError extends KontextError {\n  constructor(\n    message = \"Network error. Check your internet connection and that the server is reachable.\",\n    options?: {\n      cause?: unknown;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n    },\n  ) {\n    super(message, \"kontext_network_error\", options);\n    this.name = \"NetworkError\";\n  }\n}\n\n// ============================================================================\n// HTTP response errors (differentiated by code)\n// ============================================================================\n\n/**\n * Thrown when the server returns an HTTP error.\n * Use `error.code` to distinguish between specific error types.\n */\nexport class HttpError extends KontextError {\n  readonly retryAfter?: number;\n  readonly validationErrors?: Array<{ field: string; message: string }>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      retryAfter?: number;\n      validationErrors?: Array<{ field: string; message: string }>;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode,\n      ...options,\n    });\n    this.name = \"HttpError\";\n    this.retryAfter = options?.retryAfter;\n    this.validationErrors = options?.validationErrors;\n  }\n}\n\n// ============================================================================\n// Network error detection (used by translateError)\n// ============================================================================\n\n/**\n * Safely access arbitrary properties on an error object.\n * Errors in JS frequently carry extra properties (code, statusCode, etc.)\n * that aren't part of the Error interface. This avoids `as unknown as` casts.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction errorProps(err: Error): Record<string, any> {\n  return err;\n}\n\nconst NETWORK_ERROR_CODES = new Set([\n  \"ECONNREFUSED\",\n  \"ENOTFOUND\",\n  \"ETIMEDOUT\",\n  \"ECONNRESET\",\n  \"ECONNABORTED\",\n  \"EPIPE\",\n  \"UND_ERR_CONNECT_TIMEOUT\",\n]);\n\n/**\n * Detect network errors structurally rather than by string matching.\n * Checks Node.js system error codes on the error and its cause.\n */\nexport function isNetworkError(err: Error): boolean {\n  if (err.name === \"AbortError\") return true;\n\n  const props = errorProps(err);\n  const sysCode = props.code as string | undefined;\n  if (typeof sysCode === \"string\" && NETWORK_ERROR_CODES.has(sysCode))\n    return true;\n\n  // fetch() throws TypeError — only classify as network error when cause\n  // indicates a system-level failure\n  if (err.name === \"TypeError\" && err.cause instanceof Error) {\n    const causeCode = errorProps(err.cause).code;\n    if (typeof causeCode === \"string\" && NETWORK_ERROR_CODES.has(causeCode))\n      return true;\n  }\n\n  return false;\n}\n\n/**\n * Detect unauthorized errors structurally.\n * Checks status code and numeric code rather than string matching on name.\n */\nexport function isUnauthorizedError(err: Error): boolean {\n  const props = errorProps(err);\n\n  // Check HTTP status code (most reliable)\n  if (props.statusCode === 401 || props.status === 401) return true;\n\n  // Check MCP SDK UnauthorizedError by name (last resort, but needed for\n  // MCP SDK errors which don't set statusCode)\n  if (err.name === \"UnauthorizedError\") return true;\n  if (err.message === \"Unauthorized\") return true;\n\n  return false;\n}\n\n// ============================================================================\n// Elicitation types\n// ============================================================================\n\nexport interface ElicitationEntry {\n  readonly url: string;\n  readonly message: string;\n  readonly elicitationId: string;\n  readonly integrationId?: string;\n  readonly integrationName?: string;\n}\n\n// ============================================================================\n// HTTP error parsing\n// ============================================================================\n\n/**\n * Parse an HTTP response into an appropriate error.\n */\nexport function parseHttpError(\n  statusCode: number,\n  body?: unknown,\n): KontextError {\n  const message =\n    typeof body === \"object\" && body !== null && \"message\" in body\n      ? String((body as { message: unknown }).message)\n      : `HTTP ${statusCode}`;\n\n  const errorCode =\n    typeof body === \"object\" && body !== null && \"code\" in body\n      ? String((body as { code: unknown }).code)\n      : undefined;\n\n  switch (statusCode) {\n    case 400:\n      if (\n        typeof body === \"object\" &&\n        body !== null &&\n        \"errors\" in body &&\n        Array.isArray((body as { errors: unknown }).errors)\n      ) {\n        return new HttpError(message, \"kontext_validation_error\", {\n          statusCode: 400,\n          validationErrors: (\n            body as { errors: Array<{ field: string; message: string }> }\n          ).errors,\n        });\n      }\n      return new KontextError(message, errorCode ?? \"kontext_bad_request\", {\n        statusCode: 400,\n      });\n\n    case 401:\n      return new AuthorizationRequiredError(message);\n\n    case 403:\n      if (errorCode === \"INTEGRATION_CONNECTION_REQUIRED\") {\n        const details = body as {\n          integrationId?: string;\n          integrationName?: string;\n          connectUrl?: string;\n        };\n        return new IntegrationConnectionRequiredError(\n          details.integrationId ?? \"unknown\",\n          {\n            integrationName: details.integrationName,\n            connectUrl: details.connectUrl,\n            message,\n          },\n        );\n      }\n      return new HttpError(message, \"kontext_policy_denied\", {\n        statusCode: 403,\n        meta: { policy: (body as Record<string, unknown>)?.policy },\n      });\n\n    case 404:\n      return new HttpError(message, \"kontext_not_found\", { statusCode: 404 });\n\n    case 429: {\n      const retryAfter =\n        typeof body === \"object\" && body !== null && \"retryAfter\" in body\n          ? Number((body as { retryAfter: unknown }).retryAfter)\n          : undefined;\n      return new HttpError(\n        retryAfter\n          ? `Rate limit exceeded. Retry after ${retryAfter} seconds.`\n          : \"Rate limit exceeded. Wait and retry.\",\n        \"kontext_rate_limited\",\n        { statusCode: 429, retryAfter },\n      );\n    }\n\n    default:\n      if (statusCode >= 500) {\n        return new HttpError(\n          `Server error (HTTP ${statusCode}): ${message}`,\n          \"kontext_server_error\",\n          { statusCode },\n        );\n      }\n      return new KontextError(message, errorCode ?? \"kontext_unknown_error\", {\n        statusCode,\n      });\n  }\n}\n"]}
+{"version":3,"sources":["../src/errors.ts"],"names":["ErrorCode"],"mappings":"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","file":"errors.cjs","sourcesContent":["/**\n * Typed error classes for the Kontext SDK.\n *\n * Every error has a `kontext_` prefixed code, an auto-generated docsUrl,\n * and a `kontextError` brand for type narrowing without instanceof.\n *\n * @packageDocumentation\n */\n\nimport { ErrorCode } from \"@modelcontextprotocol/sdk/types.js\";\n\n// ============================================================================\n// Base\n// ============================================================================\n\n/**\n * Base error class for all Kontext SDK errors.\n *\n * @example\n * ```typescript\n * import { isKontextError } from '@kontext-dev/js-sdk';\n *\n * try {\n *   await client.connect();\n * } catch (err) {\n *   if (isKontextError(err)) {\n *     console.log(err.code);    // \"kontext_authorization_required\"\n *     console.log(err.docsUrl); // \"https://docs.kontext.dev/errors/kontext_authorization_required\"\n *   }\n * }\n * ```\n */\nexport class KontextError extends Error {\n  /** Brand field for type narrowing without instanceof */\n  readonly kontextError = true as const;\n\n  /** Machine-readable error code, always prefixed with `kontext_` */\n  readonly code: string;\n\n  /** HTTP status code when applicable */\n  readonly statusCode?: number;\n\n  /** Auto-generated link to error documentation */\n  readonly docsUrl: string;\n\n  /** Server request ID for debugging / support escalation */\n  readonly requestId?: string;\n\n  /** Contextual metadata bag (integration IDs, param names, etc.) */\n  readonly meta: Record<string, unknown>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options?.cause });\n    this.name = \"KontextError\";\n    this.code = code;\n    this.statusCode = options?.statusCode;\n    this.requestId = options?.requestId;\n    this.meta = options?.meta ?? {};\n    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      statusCode: this.statusCode,\n      docsUrl: this.docsUrl,\n      requestId: this.requestId,\n      meta: Object.keys(this.meta).length > 0 ? this.meta : undefined,\n    };\n  }\n\n  override toString(): string {\n    const parts = [`[${this.code}] ${this.message}`];\n    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);\n    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);\n    return parts.join(\"\\n\");\n  }\n}\n\n// ============================================================================\n// Type guard\n// ============================================================================\n\n/**\n * Check if an error is a KontextError without instanceof.\n * Works across package versions and bundler deduplication.\n */\nexport function isKontextError(err: unknown): err is KontextError {\n  return (\n    typeof err === \"object\" &&\n    err !== null &&\n    (err as Record<string, unknown>).kontextError === true\n  );\n}\n\n// ============================================================================\n// Auth errors\n// ============================================================================\n\n/**\n * Thrown when authentication is required but no valid credentials are available.\n */\nexport class AuthorizationRequiredError extends KontextError {\n  readonly authorizationUrl?: string;\n\n  constructor(\n    message = \"Authorization required. Complete the OAuth flow to continue.\",\n    options?: {\n      authorizationUrl?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, \"kontext_authorization_required\", {\n      statusCode: 401,\n      ...options,\n    });\n    this.name = \"AuthorizationRequiredError\";\n    this.authorizationUrl = options?.authorizationUrl;\n  }\n}\n\n// ============================================================================\n// OAuth errors\n// ============================================================================\n\n/**\n * Thrown when an OAuth flow fails — state validation, token exchange,\n * missing code verifier, or provider errors.\n */\nexport class OAuthError extends KontextError {\n  readonly errorCode?: string;\n  readonly errorDescription?: string;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      errorCode?: string;\n      errorDescription?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode ?? 400,\n      ...options,\n    });\n    this.name = \"OAuthError\";\n    this.errorCode = options?.errorCode;\n    this.errorDescription = options?.errorDescription;\n  }\n}\n\n// ============================================================================\n// Integration errors\n// ============================================================================\n\n/**\n * Thrown when an integration connection is required before a tool can be used.\n */\nexport class IntegrationConnectionRequiredError extends KontextError {\n  readonly integrationId: string;\n  readonly integrationName?: string;\n  readonly connectUrl?: string;\n\n  constructor(\n    integrationId: string,\n    options?: {\n      integrationName?: string;\n      connectUrl?: string;\n      message?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(\n      options?.message ??\n        `Connection to integration \"${integrationId}\" is required. Visit the connect URL to authorize.`,\n      \"kontext_integration_connection_required\",\n      { statusCode: 403, ...options },\n    );\n    this.name = \"IntegrationConnectionRequiredError\";\n    this.integrationId = integrationId;\n    this.integrationName = options?.integrationName;\n    this.connectUrl = options?.connectUrl;\n  }\n}\n\n// ============================================================================\n// Config errors (NEW — replaces all plain Error config throws)\n// ============================================================================\n\n/**\n * Thrown when SDK configuration is invalid or missing.\n * These are deterministic errors caught at initialization time.\n */\nexport class ConfigError extends KontextError {\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, options);\n    this.name = \"ConfigError\";\n  }\n}\n\n// ============================================================================\n// Network errors\n// ============================================================================\n\n/**\n * Thrown when there is a network or connection error.\n */\nexport class NetworkError extends KontextError {\n  constructor(\n    message = \"Network error. Check your internet connection and that the server is reachable.\",\n    options?: {\n      cause?: unknown;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n    },\n  ) {\n    super(message, \"kontext_network_error\", options);\n    this.name = \"NetworkError\";\n  }\n}\n\n// ============================================================================\n// HTTP response errors (differentiated by code)\n// ============================================================================\n\n/**\n * Thrown when the server returns an HTTP error.\n * Use `error.code` to distinguish between specific error types.\n */\nexport class HttpError extends KontextError {\n  readonly retryAfter?: number;\n  readonly validationErrors?: Array<{ field: string; message: string }>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      retryAfter?: number;\n      validationErrors?: Array<{ field: string; message: string }>;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode,\n      ...options,\n    });\n    this.name = \"HttpError\";\n    this.retryAfter = options?.retryAfter;\n    this.validationErrors = options?.validationErrors;\n  }\n}\n\n// ============================================================================\n// Network error detection (used by translateError)\n// ============================================================================\n\n/**\n * Safely access arbitrary properties on an error object.\n * Errors in JS frequently carry extra properties (code, statusCode, etc.)\n * that aren't part of the Error interface. This avoids `as unknown as` casts.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction errorProps(err: Error): Record<string, any> {\n  return err;\n}\n\nconst NETWORK_ERROR_CODES = new Set([\n  \"ECONNREFUSED\",\n  \"ENOTFOUND\",\n  \"ETIMEDOUT\",\n  \"ECONNRESET\",\n  \"ECONNABORTED\",\n  \"EPIPE\",\n  \"UND_ERR_CONNECT_TIMEOUT\",\n]);\n\n/**\n * Detect network errors structurally rather than by string matching.\n * Checks Node.js system error codes on the error and its cause.\n */\nexport function isNetworkError(err: Error): boolean {\n  if (err.name === \"AbortError\") return true;\n\n  const props = errorProps(err);\n  const sysCode = props.code as string | undefined;\n  if (typeof sysCode === \"string\" && NETWORK_ERROR_CODES.has(sysCode))\n    return true;\n\n  // fetch() throws TypeError — only classify as network error when cause\n  // indicates a system-level failure\n  if (err.name === \"TypeError\" && err.cause instanceof Error) {\n    const causeCode = errorProps(err.cause).code;\n    if (typeof causeCode === \"string\" && NETWORK_ERROR_CODES.has(causeCode))\n      return true;\n  }\n\n  // Browser fetch() failures: TypeError with known messages, no system error code\n  if (err.name === \"TypeError\") {\n    const msg = err.message.toLowerCase();\n    if (\n      msg === \"failed to fetch\" ||\n      msg === \"load failed\" ||\n      msg.includes(\"networkerror\")\n    ) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Detect unauthorized errors structurally.\n * Checks status code and numeric code rather than string matching on name.\n */\nexport function isUnauthorizedError(err: Error): boolean {\n  const props = errorProps(err);\n\n  // Check HTTP status code (most reliable)\n  if (props.statusCode === 401 || props.status === 401) return true;\n\n  // StreamableHTTPError stores status as `.code`\n  if (props.code === 401) return true;\n\n  // MCP SDK UnauthorizedError extends Error without setting `.name`,\n  // so `.name` is \"Error\". Use constructor name as fallback.\n  if (err.name === \"UnauthorizedError\") return true;\n  if (err.constructor?.name === \"UnauthorizedError\") return true;\n  if (err.message === \"Unauthorized\") return true;\n\n  return false;\n}\n\n// ============================================================================\n// Elicitation types\n// ============================================================================\n\nexport interface ElicitationEntry {\n  readonly url: string;\n  readonly message: string;\n  readonly elicitationId: string;\n  readonly integrationId?: string;\n  readonly integrationName?: string;\n}\n\n// ============================================================================\n// HTTP error parsing\n// ============================================================================\n\n/**\n * Parse an HTTP response into an appropriate error.\n */\nexport function parseHttpError(\n  statusCode: number,\n  body?: unknown,\n): KontextError {\n  const message =\n    typeof body === \"object\" && body !== null && \"message\" in body\n      ? String((body as { message: unknown }).message)\n      : `HTTP ${statusCode}`;\n\n  const errorCode =\n    typeof body === \"object\" && body !== null && \"code\" in body\n      ? String((body as { code: unknown }).code)\n      : undefined;\n\n  switch (statusCode) {\n    case 400:\n      if (\n        typeof body === \"object\" &&\n        body !== null &&\n        \"errors\" in body &&\n        Array.isArray((body as { errors: unknown }).errors)\n      ) {\n        return new HttpError(message, \"kontext_validation_error\", {\n          statusCode: 400,\n          validationErrors: (\n            body as { errors: Array<{ field: string; message: string }> }\n          ).errors,\n        });\n      }\n      return new KontextError(message, errorCode ?? \"kontext_bad_request\", {\n        statusCode: 400,\n      });\n\n    case 401:\n      return new AuthorizationRequiredError(message);\n\n    case 403:\n      if (errorCode === \"INTEGRATION_CONNECTION_REQUIRED\") {\n        const details = body as {\n          integrationId?: string;\n          integrationName?: string;\n          connectUrl?: string;\n        };\n        return new IntegrationConnectionRequiredError(\n          details.integrationId ?? \"unknown\",\n          {\n            integrationName: details.integrationName,\n            connectUrl: details.connectUrl,\n            message,\n          },\n        );\n      }\n      return new HttpError(message, \"kontext_policy_denied\", {\n        statusCode: 403,\n        meta: { policy: (body as Record<string, unknown>)?.policy },\n      });\n\n    case 404:\n      return new HttpError(message, \"kontext_not_found\", { statusCode: 404 });\n\n    case 429: {\n      const retryAfter =\n        typeof body === \"object\" && body !== null && \"retryAfter\" in body\n          ? Number((body as { retryAfter: unknown }).retryAfter)\n          : undefined;\n      return new HttpError(\n        retryAfter\n          ? `Rate limit exceeded. Retry after ${retryAfter} seconds.`\n          : \"Rate limit exceeded. Wait and retry.\",\n        \"kontext_rate_limited\",\n        { statusCode: 429, retryAfter },\n      );\n    }\n\n    default:\n      if (statusCode >= 500) {\n        return new HttpError(\n          `Server error (HTTP ${statusCode}): ${message}`,\n          \"kontext_server_error\",\n          { statusCode },\n        );\n      }\n      return new KontextError(message, errorCode ?? \"kontext_unknown_error\", {\n        statusCode,\n      });\n  }\n}\n\n// ============================================================================\n// MCP error translation\n// ============================================================================\n\nconst MCP_CODE_MAP: Record<number, { code: string; statusCode?: number }> = {\n  [ErrorCode.ParseError]: { code: \"kontext_mcp_parse_error\" },\n  [ErrorCode.InvalidRequest]: { code: \"kontext_mcp_invalid_request\" },\n  [ErrorCode.MethodNotFound]: { code: \"kontext_mcp_method_not_found\" },\n  [ErrorCode.InvalidParams]: { code: \"kontext_mcp_invalid_params\" },\n  [ErrorCode.InternalError]: {\n    code: \"kontext_mcp_internal_error\",\n    statusCode: 500,\n  },\n  [ErrorCode.RequestTimeout]: {\n    code: \"kontext_mcp_session_expired\",\n    statusCode: 401,\n  },\n  [ErrorCode.ConnectionClosed]: { code: \"kontext_mcp_session_error\" },\n};\n\n/**\n * Translate external errors into KontextError instances.\n * Uses structural checks (numeric codes, status codes, system error codes)\n * rather than fragile string matching.\n */\nexport function translateError(err: unknown): KontextError {\n  if (isKontextError(err)) return err as KontextError;\n\n  if (!(err instanceof Error)) {\n    return new KontextError(String(err), \"kontext_unknown_error\");\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const props: Record<string, any> = err;\n\n  // 1. MCP protocol -32042 (URL elicitation required) — check numeric code\n  if (props.code === ErrorCode.UrlElicitationRequired) {\n    const elicitations = (props.elicitations ?? props.data?.elicitations) as\n      | ElicitationEntry[]\n      | undefined;\n    const elicitation = elicitations?.[0];\n    return new IntegrationConnectionRequiredError(\n      elicitation?.integrationId ?? \"unknown\",\n      {\n        integrationName: elicitation?.integrationName,\n        connectUrl: elicitation?.url,\n        message: elicitation?.message,\n        cause: err,\n      },\n    );\n  }\n\n  // 2. MCP JSON-RPC errors (standard and server-defined ranges)\n  if (typeof props.code === \"number\" && props.code < 0) {\n    const entry = MCP_CODE_MAP[props.code];\n    if (entry) {\n      return new KontextError(err.message, entry.code, {\n        statusCode: entry.statusCode,\n        cause: err,\n      });\n    }\n    return new KontextError(err.message, \"kontext_mcp_error\", {\n      cause: err,\n      meta: { mcpCode: props.code },\n    });\n  }\n\n  // 3. HTTP status on the error (from MCP SDK or fetch wrappers)\n  // StreamableHTTPError stores HTTP status as `.code` (not `.statusCode`/`.status`),\n  // so check `.code` as well when it's in the HTTP error range (400–599).\n  const statusCode = (props.statusCode ??\n    props.status ??\n    (typeof props.code === \"number\" && props.code >= 400 && props.code < 600\n      ? props.code\n      : undefined)) as number | undefined;\n  if (typeof statusCode === \"number\" && statusCode >= 400) {\n    if (statusCode === 401) {\n      return new AuthorizationRequiredError(err.message, { cause: err });\n    }\n    return new KontextError(err.message, \"kontext_server_error\", {\n      statusCode,\n      cause: err,\n    });\n  }\n\n  // 4. Auth errors — structural check\n  if (isUnauthorizedError(err)) {\n    return new AuthorizationRequiredError(err.message, { cause: err });\n  }\n\n  // 5. Network errors — structural check (system error codes, not string matching)\n  if (isNetworkError(err)) {\n    return new NetworkError(err.message, { cause: err });\n  }\n\n  // 6. Fallback\n  return new KontextError(err.message, \"kontext_unknown_error\", {\n    cause: err,\n  });\n}\n"]}

package/dist/errors.d.cts

@@ -157,5 +157,11 @@ interface ElicitationEntry {
  * Parse an HTTP response into an appropriate error.
  */
 declare function parseHttpError(statusCode: number, body?: unknown): KontextError;
+/**
+ * Translate external errors into KontextError instances.
+ * Uses structural checks (numeric codes, status codes, system error codes)
+ * rather than fragile string matching.
+ */
+declare function translateError(err: unknown): KontextError;
 
-export { AuthorizationRequiredError, ConfigError, type ElicitationEntry, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError };
+export { AuthorizationRequiredError, ConfigError, type ElicitationEntry, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError, translateError };

package/dist/errors.d.ts

@@ -157,5 +157,11 @@ interface ElicitationEntry {
  * Parse an HTTP response into an appropriate error.
  */
 declare function parseHttpError(statusCode: number, body?: unknown): KontextError;
+/**
+ * Translate external errors into KontextError instances.
+ * Uses structural checks (numeric codes, status codes, system error codes)
+ * rather than fragile string matching.
+ */
+declare function translateError(err: unknown): KontextError;
 
-export { AuthorizationRequiredError, ConfigError, type ElicitationEntry, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError };
+export { AuthorizationRequiredError, ConfigError, type ElicitationEntry, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError, translateError };

package/dist/errors.js

@@ -1,3 +1,5 @@
+import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+
 // src/errors.ts
 var KontextError = class extends Error {
   /** Brand field for type narrowing without instanceof */
@@ -131,12 +133,20 @@ function isNetworkError(err) {
     if (typeof causeCode === "string" && NETWORK_ERROR_CODES.has(causeCode))
       return true;
   }
+  if (err.name === "TypeError") {
+    const msg = err.message.toLowerCase();
+    if (msg === "failed to fetch" || msg === "load failed" || msg.includes("networkerror")) {
+      return true;
+    }
+  }
   return false;
 }
 function isUnauthorizedError(err) {
   const props = errorProps(err);
   if (props.statusCode === 401 || props.status === 401) return true;
+  if (props.code === 401) return true;
   if (err.name === "UnauthorizedError") return true;
+  if (err.constructor?.name === "UnauthorizedError") return true;
   if (err.message === "Unauthorized") return true;
   return false;
 }
@@ -195,7 +205,74 @@ function parseHttpError(statusCode, body) {
       });
   }
 }
+var MCP_CODE_MAP = {
+  [ErrorCode.ParseError]: { code: "kontext_mcp_parse_error" },
+  [ErrorCode.InvalidRequest]: { code: "kontext_mcp_invalid_request" },
+  [ErrorCode.MethodNotFound]: { code: "kontext_mcp_method_not_found" },
+  [ErrorCode.InvalidParams]: { code: "kontext_mcp_invalid_params" },
+  [ErrorCode.InternalError]: {
+    code: "kontext_mcp_internal_error",
+    statusCode: 500
+  },
+  [ErrorCode.RequestTimeout]: {
+    code: "kontext_mcp_session_expired",
+    statusCode: 401
+  },
+  [ErrorCode.ConnectionClosed]: { code: "kontext_mcp_session_error" }
+};
+function translateError(err) {
+  if (isKontextError(err)) return err;
+  if (!(err instanceof Error)) {
+    return new KontextError(String(err), "kontext_unknown_error");
+  }
+  const props = err;
+  if (props.code === ErrorCode.UrlElicitationRequired) {
+    const elicitations = props.elicitations ?? props.data?.elicitations;
+    const elicitation = elicitations?.[0];
+    return new IntegrationConnectionRequiredError(
+      elicitation?.integrationId ?? "unknown",
+      {
+        integrationName: elicitation?.integrationName,
+        connectUrl: elicitation?.url,
+        message: elicitation?.message,
+        cause: err
+      }
+    );
+  }
+  if (typeof props.code === "number" && props.code < 0) {
+    const entry = MCP_CODE_MAP[props.code];
+    if (entry) {
+      return new KontextError(err.message, entry.code, {
+        statusCode: entry.statusCode,
+        cause: err
+      });
+    }
+    return new KontextError(err.message, "kontext_mcp_error", {
+      cause: err,
+      meta: { mcpCode: props.code }
+    });
+  }
+  const statusCode = props.statusCode ?? props.status ?? (typeof props.code === "number" && props.code >= 400 && props.code < 600 ? props.code : void 0);
+  if (typeof statusCode === "number" && statusCode >= 400) {
+    if (statusCode === 401) {
+      return new AuthorizationRequiredError(err.message, { cause: err });
+    }
+    return new KontextError(err.message, "kontext_server_error", {
+      statusCode,
+      cause: err
+    });
+  }
+  if (isUnauthorizedError(err)) {
+    return new AuthorizationRequiredError(err.message, { cause: err });
+  }
+  if (isNetworkError(err)) {
+    return new NetworkError(err.message, { cause: err });
+  }
+  return new KontextError(err.message, "kontext_unknown_error", {
+    cause: err
+  });
+}
 
-export { AuthorizationRequiredError, ConfigError, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError };
+export { AuthorizationRequiredError, ConfigError, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError, translateError };
 //# sourceMappingURL=errors.js.map
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":"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","file":"errors.js","sourcesContent":["/**\n * Typed error classes for the Kontext SDK.\n *\n * Every error has a `kontext_` prefixed code, an auto-generated docsUrl,\n * and a `kontextError` brand for type narrowing without instanceof.\n *\n * @packageDocumentation\n */\n\n// ============================================================================\n// Base\n// ============================================================================\n\n/**\n * Base error class for all Kontext SDK errors.\n *\n * @example\n * ```typescript\n * import { isKontextError } from '@kontext-dev/js-sdk';\n *\n * try {\n *   await client.connect();\n * } catch (err) {\n *   if (isKontextError(err)) {\n *     console.log(err.code);    // \"kontext_authorization_required\"\n *     console.log(err.docsUrl); // \"https://docs.kontext.dev/errors/kontext_authorization_required\"\n *   }\n * }\n * ```\n */\nexport class KontextError extends Error {\n  /** Brand field for type narrowing without instanceof */\n  readonly kontextError = true as const;\n\n  /** Machine-readable error code, always prefixed with `kontext_` */\n  readonly code: string;\n\n  /** HTTP status code when applicable */\n  readonly statusCode?: number;\n\n  /** Auto-generated link to error documentation */\n  readonly docsUrl: string;\n\n  /** Server request ID for debugging / support escalation */\n  readonly requestId?: string;\n\n  /** Contextual metadata bag (integration IDs, param names, etc.) */\n  readonly meta: Record<string, unknown>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options?.cause });\n    this.name = \"KontextError\";\n    this.code = code;\n    this.statusCode = options?.statusCode;\n    this.requestId = options?.requestId;\n    this.meta = options?.meta ?? {};\n    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      statusCode: this.statusCode,\n      docsUrl: this.docsUrl,\n      requestId: this.requestId,\n      meta: Object.keys(this.meta).length > 0 ? this.meta : undefined,\n    };\n  }\n\n  override toString(): string {\n    const parts = [`[${this.code}] ${this.message}`];\n    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);\n    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);\n    return parts.join(\"\\n\");\n  }\n}\n\n// ============================================================================\n// Type guard\n// ============================================================================\n\n/**\n * Check if an error is a KontextError without instanceof.\n * Works across package versions and bundler deduplication.\n */\nexport function isKontextError(err: unknown): err is KontextError {\n  return (\n    typeof err === \"object\" &&\n    err !== null &&\n    (err as Record<string, unknown>).kontextError === true\n  );\n}\n\n// ============================================================================\n// Auth errors\n// ============================================================================\n\n/**\n * Thrown when authentication is required but no valid credentials are available.\n */\nexport class AuthorizationRequiredError extends KontextError {\n  readonly authorizationUrl?: string;\n\n  constructor(\n    message = \"Authorization required. Complete the OAuth flow to continue.\",\n    options?: {\n      authorizationUrl?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, \"kontext_authorization_required\", {\n      statusCode: 401,\n      ...options,\n    });\n    this.name = \"AuthorizationRequiredError\";\n    this.authorizationUrl = options?.authorizationUrl;\n  }\n}\n\n// ============================================================================\n// OAuth errors\n// ============================================================================\n\n/**\n * Thrown when an OAuth flow fails — state validation, token exchange,\n * missing code verifier, or provider errors.\n */\nexport class OAuthError extends KontextError {\n  readonly errorCode?: string;\n  readonly errorDescription?: string;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      errorCode?: string;\n      errorDescription?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode ?? 400,\n      ...options,\n    });\n    this.name = \"OAuthError\";\n    this.errorCode = options?.errorCode;\n    this.errorDescription = options?.errorDescription;\n  }\n}\n\n// ============================================================================\n// Integration errors\n// ============================================================================\n\n/**\n * Thrown when an integration connection is required before a tool can be used.\n */\nexport class IntegrationConnectionRequiredError extends KontextError {\n  readonly integrationId: string;\n  readonly integrationName?: string;\n  readonly connectUrl?: string;\n\n  constructor(\n    integrationId: string,\n    options?: {\n      integrationName?: string;\n      connectUrl?: string;\n      message?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(\n      options?.message ??\n        `Connection to integration \"${integrationId}\" is required. Visit the connect URL to authorize.`,\n      \"kontext_integration_connection_required\",\n      { statusCode: 403, ...options },\n    );\n    this.name = \"IntegrationConnectionRequiredError\";\n    this.integrationId = integrationId;\n    this.integrationName = options?.integrationName;\n    this.connectUrl = options?.connectUrl;\n  }\n}\n\n// ============================================================================\n// Config errors (NEW — replaces all plain Error config throws)\n// ============================================================================\n\n/**\n * Thrown when SDK configuration is invalid or missing.\n * These are deterministic errors caught at initialization time.\n */\nexport class ConfigError extends KontextError {\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, options);\n    this.name = \"ConfigError\";\n  }\n}\n\n// ============================================================================\n// Network errors\n// ============================================================================\n\n/**\n * Thrown when there is a network or connection error.\n */\nexport class NetworkError extends KontextError {\n  constructor(\n    message = \"Network error. Check your internet connection and that the server is reachable.\",\n    options?: {\n      cause?: unknown;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n    },\n  ) {\n    super(message, \"kontext_network_error\", options);\n    this.name = \"NetworkError\";\n  }\n}\n\n// ============================================================================\n// HTTP response errors (differentiated by code)\n// ============================================================================\n\n/**\n * Thrown when the server returns an HTTP error.\n * Use `error.code` to distinguish between specific error types.\n */\nexport class HttpError extends KontextError {\n  readonly retryAfter?: number;\n  readonly validationErrors?: Array<{ field: string; message: string }>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      retryAfter?: number;\n      validationErrors?: Array<{ field: string; message: string }>;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode,\n      ...options,\n    });\n    this.name = \"HttpError\";\n    this.retryAfter = options?.retryAfter;\n    this.validationErrors = options?.validationErrors;\n  }\n}\n\n// ============================================================================\n// Network error detection (used by translateError)\n// ============================================================================\n\n/**\n * Safely access arbitrary properties on an error object.\n * Errors in JS frequently carry extra properties (code, statusCode, etc.)\n * that aren't part of the Error interface. This avoids `as unknown as` casts.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction errorProps(err: Error): Record<string, any> {\n  return err;\n}\n\nconst NETWORK_ERROR_CODES = new Set([\n  \"ECONNREFUSED\",\n  \"ENOTFOUND\",\n  \"ETIMEDOUT\",\n  \"ECONNRESET\",\n  \"ECONNABORTED\",\n  \"EPIPE\",\n  \"UND_ERR_CONNECT_TIMEOUT\",\n]);\n\n/**\n * Detect network errors structurally rather than by string matching.\n * Checks Node.js system error codes on the error and its cause.\n */\nexport function isNetworkError(err: Error): boolean {\n  if (err.name === \"AbortError\") return true;\n\n  const props = errorProps(err);\n  const sysCode = props.code as string | undefined;\n  if (typeof sysCode === \"string\" && NETWORK_ERROR_CODES.has(sysCode))\n    return true;\n\n  // fetch() throws TypeError — only classify as network error when cause\n  // indicates a system-level failure\n  if (err.name === \"TypeError\" && err.cause instanceof Error) {\n    const causeCode = errorProps(err.cause).code;\n    if (typeof causeCode === \"string\" && NETWORK_ERROR_CODES.has(causeCode))\n      return true;\n  }\n\n  return false;\n}\n\n/**\n * Detect unauthorized errors structurally.\n * Checks status code and numeric code rather than string matching on name.\n */\nexport function isUnauthorizedError(err: Error): boolean {\n  const props = errorProps(err);\n\n  // Check HTTP status code (most reliable)\n  if (props.statusCode === 401 || props.status === 401) return true;\n\n  // Check MCP SDK UnauthorizedError by name (last resort, but needed for\n  // MCP SDK errors which don't set statusCode)\n  if (err.name === \"UnauthorizedError\") return true;\n  if (err.message === \"Unauthorized\") return true;\n\n  return false;\n}\n\n// ============================================================================\n// Elicitation types\n// ============================================================================\n\nexport interface ElicitationEntry {\n  readonly url: string;\n  readonly message: string;\n  readonly elicitationId: string;\n  readonly integrationId?: string;\n  readonly integrationName?: string;\n}\n\n// ============================================================================\n// HTTP error parsing\n// ============================================================================\n\n/**\n * Parse an HTTP response into an appropriate error.\n */\nexport function parseHttpError(\n  statusCode: number,\n  body?: unknown,\n): KontextError {\n  const message =\n    typeof body === \"object\" && body !== null && \"message\" in body\n      ? String((body as { message: unknown }).message)\n      : `HTTP ${statusCode}`;\n\n  const errorCode =\n    typeof body === \"object\" && body !== null && \"code\" in body\n      ? String((body as { code: unknown }).code)\n      : undefined;\n\n  switch (statusCode) {\n    case 400:\n      if (\n        typeof body === \"object\" &&\n        body !== null &&\n        \"errors\" in body &&\n        Array.isArray((body as { errors: unknown }).errors)\n      ) {\n        return new HttpError(message, \"kontext_validation_error\", {\n          statusCode: 400,\n          validationErrors: (\n            body as { errors: Array<{ field: string; message: string }> }\n          ).errors,\n        });\n      }\n      return new KontextError(message, errorCode ?? \"kontext_bad_request\", {\n        statusCode: 400,\n      });\n\n    case 401:\n      return new AuthorizationRequiredError(message);\n\n    case 403:\n      if (errorCode === \"INTEGRATION_CONNECTION_REQUIRED\") {\n        const details = body as {\n          integrationId?: string;\n          integrationName?: string;\n          connectUrl?: string;\n        };\n        return new IntegrationConnectionRequiredError(\n          details.integrationId ?? \"unknown\",\n          {\n            integrationName: details.integrationName,\n            connectUrl: details.connectUrl,\n            message,\n          },\n        );\n      }\n      return new HttpError(message, \"kontext_policy_denied\", {\n        statusCode: 403,\n        meta: { policy: (body as Record<string, unknown>)?.policy },\n      });\n\n    case 404:\n      return new HttpError(message, \"kontext_not_found\", { statusCode: 404 });\n\n    case 429: {\n      const retryAfter =\n        typeof body === \"object\" && body !== null && \"retryAfter\" in body\n          ? Number((body as { retryAfter: unknown }).retryAfter)\n          : undefined;\n      return new HttpError(\n        retryAfter\n          ? `Rate limit exceeded. Retry after ${retryAfter} seconds.`\n          : \"Rate limit exceeded. Wait and retry.\",\n        \"kontext_rate_limited\",\n        { statusCode: 429, retryAfter },\n      );\n    }\n\n    default:\n      if (statusCode >= 500) {\n        return new HttpError(\n          `Server error (HTTP ${statusCode}): ${message}`,\n          \"kontext_server_error\",\n          { statusCode },\n        );\n      }\n      return new KontextError(message, errorCode ?? \"kontext_unknown_error\", {\n        statusCode,\n      });\n  }\n}\n"]}
+{"version":3,"sources":["../src/errors.ts"],"names":[],"mappings":"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","file":"errors.js","sourcesContent":["/**\n * Typed error classes for the Kontext SDK.\n *\n * Every error has a `kontext_` prefixed code, an auto-generated docsUrl,\n * and a `kontextError` brand for type narrowing without instanceof.\n *\n * @packageDocumentation\n */\n\nimport { ErrorCode } from \"@modelcontextprotocol/sdk/types.js\";\n\n// ============================================================================\n// Base\n// ============================================================================\n\n/**\n * Base error class for all Kontext SDK errors.\n *\n * @example\n * ```typescript\n * import { isKontextError } from '@kontext-dev/js-sdk';\n *\n * try {\n *   await client.connect();\n * } catch (err) {\n *   if (isKontextError(err)) {\n *     console.log(err.code);    // \"kontext_authorization_required\"\n *     console.log(err.docsUrl); // \"https://docs.kontext.dev/errors/kontext_authorization_required\"\n *   }\n * }\n * ```\n */\nexport class KontextError extends Error {\n  /** Brand field for type narrowing without instanceof */\n  readonly kontextError = true as const;\n\n  /** Machine-readable error code, always prefixed with `kontext_` */\n  readonly code: string;\n\n  /** HTTP status code when applicable */\n  readonly statusCode?: number;\n\n  /** Auto-generated link to error documentation */\n  readonly docsUrl: string;\n\n  /** Server request ID for debugging / support escalation */\n  readonly requestId?: string;\n\n  /** Contextual metadata bag (integration IDs, param names, etc.) */\n  readonly meta: Record<string, unknown>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, { cause: options?.cause });\n    this.name = \"KontextError\";\n    this.code = code;\n    this.statusCode = options?.statusCode;\n    this.requestId = options?.requestId;\n    this.meta = options?.meta ?? {};\n    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  toJSON(): Record<string, unknown> {\n    return {\n      name: this.name,\n      code: this.code,\n      message: this.message,\n      statusCode: this.statusCode,\n      docsUrl: this.docsUrl,\n      requestId: this.requestId,\n      meta: Object.keys(this.meta).length > 0 ? this.meta : undefined,\n    };\n  }\n\n  override toString(): string {\n    const parts = [`[${this.code}] ${this.message}`];\n    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);\n    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);\n    return parts.join(\"\\n\");\n  }\n}\n\n// ============================================================================\n// Type guard\n// ============================================================================\n\n/**\n * Check if an error is a KontextError without instanceof.\n * Works across package versions and bundler deduplication.\n */\nexport function isKontextError(err: unknown): err is KontextError {\n  return (\n    typeof err === \"object\" &&\n    err !== null &&\n    (err as Record<string, unknown>).kontextError === true\n  );\n}\n\n// ============================================================================\n// Auth errors\n// ============================================================================\n\n/**\n * Thrown when authentication is required but no valid credentials are available.\n */\nexport class AuthorizationRequiredError extends KontextError {\n  readonly authorizationUrl?: string;\n\n  constructor(\n    message = \"Authorization required. Complete the OAuth flow to continue.\",\n    options?: {\n      authorizationUrl?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, \"kontext_authorization_required\", {\n      statusCode: 401,\n      ...options,\n    });\n    this.name = \"AuthorizationRequiredError\";\n    this.authorizationUrl = options?.authorizationUrl;\n  }\n}\n\n// ============================================================================\n// OAuth errors\n// ============================================================================\n\n/**\n * Thrown when an OAuth flow fails — state validation, token exchange,\n * missing code verifier, or provider errors.\n */\nexport class OAuthError extends KontextError {\n  readonly errorCode?: string;\n  readonly errorDescription?: string;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      errorCode?: string;\n      errorDescription?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode ?? 400,\n      ...options,\n    });\n    this.name = \"OAuthError\";\n    this.errorCode = options?.errorCode;\n    this.errorDescription = options?.errorDescription;\n  }\n}\n\n// ============================================================================\n// Integration errors\n// ============================================================================\n\n/**\n * Thrown when an integration connection is required before a tool can be used.\n */\nexport class IntegrationConnectionRequiredError extends KontextError {\n  readonly integrationId: string;\n  readonly integrationName?: string;\n  readonly connectUrl?: string;\n\n  constructor(\n    integrationId: string,\n    options?: {\n      integrationName?: string;\n      connectUrl?: string;\n      message?: string;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(\n      options?.message ??\n        `Connection to integration \"${integrationId}\" is required. Visit the connect URL to authorize.`,\n      \"kontext_integration_connection_required\",\n      { statusCode: 403, ...options },\n    );\n    this.name = \"IntegrationConnectionRequiredError\";\n    this.integrationId = integrationId;\n    this.integrationName = options?.integrationName;\n    this.connectUrl = options?.connectUrl;\n  }\n}\n\n// ============================================================================\n// Config errors (NEW — replaces all plain Error config throws)\n// ============================================================================\n\n/**\n * Thrown when SDK configuration is invalid or missing.\n * These are deterministic errors caught at initialization time.\n */\nexport class ConfigError extends KontextError {\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, options);\n    this.name = \"ConfigError\";\n  }\n}\n\n// ============================================================================\n// Network errors\n// ============================================================================\n\n/**\n * Thrown when there is a network or connection error.\n */\nexport class NetworkError extends KontextError {\n  constructor(\n    message = \"Network error. Check your internet connection and that the server is reachable.\",\n    options?: {\n      cause?: unknown;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n    },\n  ) {\n    super(message, \"kontext_network_error\", options);\n    this.name = \"NetworkError\";\n  }\n}\n\n// ============================================================================\n// HTTP response errors (differentiated by code)\n// ============================================================================\n\n/**\n * Thrown when the server returns an HTTP error.\n * Use `error.code` to distinguish between specific error types.\n */\nexport class HttpError extends KontextError {\n  readonly retryAfter?: number;\n  readonly validationErrors?: Array<{ field: string; message: string }>;\n\n  constructor(\n    message: string,\n    code: string,\n    options?: {\n      statusCode?: number;\n      retryAfter?: number;\n      validationErrors?: Array<{ field: string; message: string }>;\n      requestId?: string;\n      meta?: Record<string, unknown>;\n      cause?: unknown;\n    },\n  ) {\n    super(message, code, {\n      statusCode: options?.statusCode,\n      ...options,\n    });\n    this.name = \"HttpError\";\n    this.retryAfter = options?.retryAfter;\n    this.validationErrors = options?.validationErrors;\n  }\n}\n\n// ============================================================================\n// Network error detection (used by translateError)\n// ============================================================================\n\n/**\n * Safely access arbitrary properties on an error object.\n * Errors in JS frequently carry extra properties (code, statusCode, etc.)\n * that aren't part of the Error interface. This avoids `as unknown as` casts.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nfunction errorProps(err: Error): Record<string, any> {\n  return err;\n}\n\nconst NETWORK_ERROR_CODES = new Set([\n  \"ECONNREFUSED\",\n  \"ENOTFOUND\",\n  \"ETIMEDOUT\",\n  \"ECONNRESET\",\n  \"ECONNABORTED\",\n  \"EPIPE\",\n  \"UND_ERR_CONNECT_TIMEOUT\",\n]);\n\n/**\n * Detect network errors structurally rather than by string matching.\n * Checks Node.js system error codes on the error and its cause.\n */\nexport function isNetworkError(err: Error): boolean {\n  if (err.name === \"AbortError\") return true;\n\n  const props = errorProps(err);\n  const sysCode = props.code as string | undefined;\n  if (typeof sysCode === \"string\" && NETWORK_ERROR_CODES.has(sysCode))\n    return true;\n\n  // fetch() throws TypeError — only classify as network error when cause\n  // indicates a system-level failure\n  if (err.name === \"TypeError\" && err.cause instanceof Error) {\n    const causeCode = errorProps(err.cause).code;\n    if (typeof causeCode === \"string\" && NETWORK_ERROR_CODES.has(causeCode))\n      return true;\n  }\n\n  // Browser fetch() failures: TypeError with known messages, no system error code\n  if (err.name === \"TypeError\") {\n    const msg = err.message.toLowerCase();\n    if (\n      msg === \"failed to fetch\" ||\n      msg === \"load failed\" ||\n      msg.includes(\"networkerror\")\n    ) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Detect unauthorized errors structurally.\n * Checks status code and numeric code rather than string matching on name.\n */\nexport function isUnauthorizedError(err: Error): boolean {\n  const props = errorProps(err);\n\n  // Check HTTP status code (most reliable)\n  if (props.statusCode === 401 || props.status === 401) return true;\n\n  // StreamableHTTPError stores status as `.code`\n  if (props.code === 401) return true;\n\n  // MCP SDK UnauthorizedError extends Error without setting `.name`,\n  // so `.name` is \"Error\". Use constructor name as fallback.\n  if (err.name === \"UnauthorizedError\") return true;\n  if (err.constructor?.name === \"UnauthorizedError\") return true;\n  if (err.message === \"Unauthorized\") return true;\n\n  return false;\n}\n\n// ============================================================================\n// Elicitation types\n// ============================================================================\n\nexport interface ElicitationEntry {\n  readonly url: string;\n  readonly message: string;\n  readonly elicitationId: string;\n  readonly integrationId?: string;\n  readonly integrationName?: string;\n}\n\n// ============================================================================\n// HTTP error parsing\n// ============================================================================\n\n/**\n * Parse an HTTP response into an appropriate error.\n */\nexport function parseHttpError(\n  statusCode: number,\n  body?: unknown,\n): KontextError {\n  const message =\n    typeof body === \"object\" && body !== null && \"message\" in body\n      ? String((body as { message: unknown }).message)\n      : `HTTP ${statusCode}`;\n\n  const errorCode =\n    typeof body === \"object\" && body !== null && \"code\" in body\n      ? String((body as { code: unknown }).code)\n      : undefined;\n\n  switch (statusCode) {\n    case 400:\n      if (\n        typeof body === \"object\" &&\n        body !== null &&\n        \"errors\" in body &&\n        Array.isArray((body as { errors: unknown }).errors)\n      ) {\n        return new HttpError(message, \"kontext_validation_error\", {\n          statusCode: 400,\n          validationErrors: (\n            body as { errors: Array<{ field: string; message: string }> }\n          ).errors,\n        });\n      }\n      return new KontextError(message, errorCode ?? \"kontext_bad_request\", {\n        statusCode: 400,\n      });\n\n    case 401:\n      return new AuthorizationRequiredError(message);\n\n    case 403:\n      if (errorCode === \"INTEGRATION_CONNECTION_REQUIRED\") {\n        const details = body as {\n          integrationId?: string;\n          integrationName?: string;\n          connectUrl?: string;\n        };\n        return new IntegrationConnectionRequiredError(\n          details.integrationId ?? \"unknown\",\n          {\n            integrationName: details.integrationName,\n            connectUrl: details.connectUrl,\n            message,\n          },\n        );\n      }\n      return new HttpError(message, \"kontext_policy_denied\", {\n        statusCode: 403,\n        meta: { policy: (body as Record<string, unknown>)?.policy },\n      });\n\n    case 404:\n      return new HttpError(message, \"kontext_not_found\", { statusCode: 404 });\n\n    case 429: {\n      const retryAfter =\n        typeof body === \"object\" && body !== null && \"retryAfter\" in body\n          ? Number((body as { retryAfter: unknown }).retryAfter)\n          : undefined;\n      return new HttpError(\n        retryAfter\n          ? `Rate limit exceeded. Retry after ${retryAfter} seconds.`\n          : \"Rate limit exceeded. Wait and retry.\",\n        \"kontext_rate_limited\",\n        { statusCode: 429, retryAfter },\n      );\n    }\n\n    default:\n      if (statusCode >= 500) {\n        return new HttpError(\n          `Server error (HTTP ${statusCode}): ${message}`,\n          \"kontext_server_error\",\n          { statusCode },\n        );\n      }\n      return new KontextError(message, errorCode ?? \"kontext_unknown_error\", {\n        statusCode,\n      });\n  }\n}\n\n// ============================================================================\n// MCP error translation\n// ============================================================================\n\nconst MCP_CODE_MAP: Record<number, { code: string; statusCode?: number }> = {\n  [ErrorCode.ParseError]: { code: \"kontext_mcp_parse_error\" },\n  [ErrorCode.InvalidRequest]: { code: \"kontext_mcp_invalid_request\" },\n  [ErrorCode.MethodNotFound]: { code: \"kontext_mcp_method_not_found\" },\n  [ErrorCode.InvalidParams]: { code: \"kontext_mcp_invalid_params\" },\n  [ErrorCode.InternalError]: {\n    code: \"kontext_mcp_internal_error\",\n    statusCode: 500,\n  },\n  [ErrorCode.RequestTimeout]: {\n    code: \"kontext_mcp_session_expired\",\n    statusCode: 401,\n  },\n  [ErrorCode.ConnectionClosed]: { code: \"kontext_mcp_session_error\" },\n};\n\n/**\n * Translate external errors into KontextError instances.\n * Uses structural checks (numeric codes, status codes, system error codes)\n * rather than fragile string matching.\n */\nexport function translateError(err: unknown): KontextError {\n  if (isKontextError(err)) return err as KontextError;\n\n  if (!(err instanceof Error)) {\n    return new KontextError(String(err), \"kontext_unknown_error\");\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const props: Record<string, any> = err;\n\n  // 1. MCP protocol -32042 (URL elicitation required) — check numeric code\n  if (props.code === ErrorCode.UrlElicitationRequired) {\n    const elicitations = (props.elicitations ?? props.data?.elicitations) as\n      | ElicitationEntry[]\n      | undefined;\n    const elicitation = elicitations?.[0];\n    return new IntegrationConnectionRequiredError(\n      elicitation?.integrationId ?? \"unknown\",\n      {\n        integrationName: elicitation?.integrationName,\n        connectUrl: elicitation?.url,\n        message: elicitation?.message,\n        cause: err,\n      },\n    );\n  }\n\n  // 2. MCP JSON-RPC errors (standard and server-defined ranges)\n  if (typeof props.code === \"number\" && props.code < 0) {\n    const entry = MCP_CODE_MAP[props.code];\n    if (entry) {\n      return new KontextError(err.message, entry.code, {\n        statusCode: entry.statusCode,\n        cause: err,\n      });\n    }\n    return new KontextError(err.message, \"kontext_mcp_error\", {\n      cause: err,\n      meta: { mcpCode: props.code },\n    });\n  }\n\n  // 3. HTTP status on the error (from MCP SDK or fetch wrappers)\n  // StreamableHTTPError stores HTTP status as `.code` (not `.statusCode`/`.status`),\n  // so check `.code` as well when it's in the HTTP error range (400–599).\n  const statusCode = (props.statusCode ??\n    props.status ??\n    (typeof props.code === \"number\" && props.code >= 400 && props.code < 600\n      ? props.code\n      : undefined)) as number | undefined;\n  if (typeof statusCode === \"number\" && statusCode >= 400) {\n    if (statusCode === 401) {\n      return new AuthorizationRequiredError(err.message, { cause: err });\n    }\n    return new KontextError(err.message, \"kontext_server_error\", {\n      statusCode,\n      cause: err,\n    });\n  }\n\n  // 4. Auth errors — structural check\n  if (isUnauthorizedError(err)) {\n    return new AuthorizationRequiredError(err.message, { cause: err });\n  }\n\n  // 5. Network errors — structural check (system error codes, not string matching)\n  if (isNetworkError(err)) {\n    return new NetworkError(err.message, { cause: err });\n  }\n\n  // 6. Fallback\n  return new KontextError(err.message, \"kontext_unknown_error\", {\n    cause: err,\n  });\n}\n"]}