@kontext-dev/js-sdk 0.1.0

package/dist/errors.js

@@ -0,0 +1,201 @@
+// src/errors.ts
+var KontextError = class extends Error {
+  /** Brand field for type narrowing without instanceof */
+  kontextError = true;
+  /** Machine-readable error code, always prefixed with `kontext_` */
+  code;
+  /** HTTP status code when applicable */
+  statusCode;
+  /** Auto-generated link to error documentation */
+  docsUrl;
+  /** Server request ID for debugging / support escalation */
+  requestId;
+  /** Contextual metadata bag (integration IDs, param names, etc.) */
+  meta;
+  constructor(message, code, options) {
+    super(message, { cause: options?.cause });
+    this.name = "KontextError";
+    this.code = code;
+    this.statusCode = options?.statusCode;
+    this.requestId = options?.requestId;
+    this.meta = options?.meta ?? {};
+    this.docsUrl = `https://docs.kontext.dev/errors/${code}`;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      docsUrl: this.docsUrl,
+      requestId: this.requestId,
+      meta: Object.keys(this.meta).length > 0 ? this.meta : void 0
+    };
+  }
+  toString() {
+    const parts = [`[${this.code}] ${this.message}`];
+    if (this.docsUrl) parts.push(`Docs: ${this.docsUrl}`);
+    if (this.requestId) parts.push(`Request ID: ${this.requestId}`);
+    return parts.join("\n");
+  }
+};
+function isKontextError(err) {
+  return typeof err === "object" && err !== null && err.kontextError === true;
+}
+var AuthorizationRequiredError = class extends KontextError {
+  authorizationUrl;
+  constructor(message = "Authorization required. Complete the OAuth flow to continue.", options) {
+    super(message, "kontext_authorization_required", {
+      statusCode: 401,
+      ...options
+    });
+    this.name = "AuthorizationRequiredError";
+    this.authorizationUrl = options?.authorizationUrl;
+  }
+};
+var OAuthError = class extends KontextError {
+  errorCode;
+  errorDescription;
+  constructor(message, code, options) {
+    super(message, code, {
+      statusCode: options?.statusCode ?? 400,
+      ...options
+    });
+    this.name = "OAuthError";
+    this.errorCode = options?.errorCode;
+    this.errorDescription = options?.errorDescription;
+  }
+};
+var IntegrationConnectionRequiredError = class extends KontextError {
+  integrationId;
+  integrationName;
+  connectUrl;
+  constructor(integrationId, options) {
+    super(
+      options?.message ?? `Connection to integration "${integrationId}" is required. Visit the connect URL to authorize.`,
+      "kontext_integration_connection_required",
+      { statusCode: 403, ...options }
+    );
+    this.name = "IntegrationConnectionRequiredError";
+    this.integrationId = integrationId;
+    this.integrationName = options?.integrationName;
+    this.connectUrl = options?.connectUrl;
+  }
+};
+var ConfigError = class extends KontextError {
+  constructor(message, code, options) {
+    super(message, code, options);
+    this.name = "ConfigError";
+  }
+};
+var NetworkError = class extends KontextError {
+  constructor(message = "Network error. Check your internet connection and that the server is reachable.", options) {
+    super(message, "kontext_network_error", options);
+    this.name = "NetworkError";
+  }
+};
+var HttpError = class extends KontextError {
+  retryAfter;
+  validationErrors;
+  constructor(message, code, options) {
+    super(message, code, {
+      statusCode: options?.statusCode,
+      ...options
+    });
+    this.name = "HttpError";
+    this.retryAfter = options?.retryAfter;
+    this.validationErrors = options?.validationErrors;
+  }
+};
+function errorProps(err) {
+  return err;
+}
+var NETWORK_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "ECONNABORTED",
+  "EPIPE",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+function isNetworkError(err) {
+  if (err.name === "AbortError") return true;
+  const props = errorProps(err);
+  const sysCode = props.code;
+  if (typeof sysCode === "string" && NETWORK_ERROR_CODES.has(sysCode))
+    return true;
+  if (err.name === "TypeError" && err.cause instanceof Error) {
+    const causeCode = errorProps(err.cause).code;
+    if (typeof causeCode === "string" && NETWORK_ERROR_CODES.has(causeCode))
+      return true;
+  }
+  return false;
+}
+function isUnauthorizedError(err) {
+  const props = errorProps(err);
+  if (props.statusCode === 401 || props.status === 401) return true;
+  if (err.name === "UnauthorizedError") return true;
+  if (err.message === "Unauthorized") return true;
+  return false;
+}
+function parseHttpError(statusCode, body) {
+  const message = typeof body === "object" && body !== null && "message" in body ? String(body.message) : `HTTP ${statusCode}`;
+  const errorCode = typeof body === "object" && body !== null && "code" in body ? String(body.code) : void 0;
+  switch (statusCode) {
+    case 400:
+      if (typeof body === "object" && body !== null && "errors" in body && Array.isArray(body.errors)) {
+        return new HttpError(message, "kontext_validation_error", {
+          statusCode: 400,
+          validationErrors: body.errors
+        });
+      }
+      return new KontextError(message, errorCode ?? "kontext_bad_request", {
+        statusCode: 400
+      });
+    case 401:
+      return new AuthorizationRequiredError(message);
+    case 403:
+      if (errorCode === "INTEGRATION_CONNECTION_REQUIRED") {
+        const details = body;
+        return new IntegrationConnectionRequiredError(
+          details.integrationId ?? "unknown",
+          {
+            integrationName: details.integrationName,
+            connectUrl: details.connectUrl,
+            message
+          }
+        );
+      }
+      return new HttpError(message, "kontext_policy_denied", {
+        statusCode: 403,
+        meta: { policy: body?.policy }
+      });
+    case 404:
+      return new HttpError(message, "kontext_not_found", { statusCode: 404 });
+    case 429: {
+      const retryAfter = typeof body === "object" && body !== null && "retryAfter" in body ? Number(body.retryAfter) : void 0;
+      return new HttpError(
+        retryAfter ? `Rate limit exceeded. Retry after ${retryAfter} seconds.` : "Rate limit exceeded. Wait and retry.",
+        "kontext_rate_limited",
+        { statusCode: 429, retryAfter }
+      );
+    }
+    default:
+      if (statusCode >= 500) {
+        return new HttpError(
+          `Server error (HTTP ${statusCode}): ${message}`,
+          "kontext_server_error",
+          { statusCode }
+        );
+      }
+      return new KontextError(message, errorCode ?? "kontext_unknown_error", {
+        statusCode
+      });
+  }
+}
+
+export { AuthorizationRequiredError, ConfigError, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError };
+//# sourceMappingURL=errors.js.map
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +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"]}

package/dist/index-D5hS5PGn.d.ts

@@ -0,0 +1,54 @@
+import { ClientState, ConnectSessionResult, IntegrationInfo, KontextTool, ToolResult, KontextClient, KontextClientConfig } from './client/index.js';
+import { K as KontextStorage } from './types-RIzHnRpk.js';
+import { KontextError } from './errors.js';
+
+type KontextOrchestratorState = ClientState;
+
+/**
+ * KontextOrchestrator — unified mixed-mode client facade.
+ *
+ * Combines:
+ * - Gateway-routed tools (gateway_remote_mcp)
+ * - Direct internal MCP tools (internal_mcp_credentials)
+ *
+ * into a single tool listing/execution surface.
+ */
+
+interface KontextOrchestratorConfig {
+    clientId: string;
+    redirectUri: string;
+    serverUrl?: string;
+    storage?: KontextStorage;
+    sessionKey?: string;
+    onAuthRequired: KontextClientConfig["onAuthRequired"];
+    onIntegrationRequired?: KontextClientConfig["onIntegrationRequired"];
+    onStateChange?: (state: KontextOrchestratorState) => void;
+}
+interface KontextOrchestrator {
+    readonly state: KontextOrchestratorState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnectPageUrl(): Promise<ConnectSessionResult>;
+    readonly auth: {
+        signIn(): Promise<void>;
+        signOut(): Promise<void>;
+        handleCallback(url: string | URL): Promise<void>;
+        isCallback(url: string | URL): boolean;
+        readonly isAuthenticated: boolean;
+    };
+    readonly integrations: {
+        list(): Promise<IntegrationInfo[]>;
+    };
+    readonly tools: {
+        list(options?: {
+            limit?: number;
+        }): Promise<KontextTool[]>;
+        execute(toolId: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    };
+    on(event: "stateChange", handler: (state: KontextOrchestratorState) => void): () => void;
+    on(event: "error", handler: (error: KontextError) => void): () => void;
+    readonly mcp: KontextClient["mcp"];
+}
+declare function createKontextOrchestrator(config: KontextOrchestratorConfig): KontextOrchestrator;
+
+export { type KontextOrchestrator as K, type KontextOrchestratorConfig as a, type KontextOrchestratorState as b, createKontextOrchestrator as c };

package/dist/index-DcL4a5Vq.d.cts

@@ -0,0 +1,54 @@
+import { ClientState, ConnectSessionResult, IntegrationInfo, KontextTool, ToolResult, KontextClient, KontextClientConfig } from './client/index.cjs';
+import { K as KontextStorage } from './types-RIzHnRpk.cjs';
+import { KontextError } from './errors.cjs';
+
+type KontextOrchestratorState = ClientState;
+
+/**
+ * KontextOrchestrator — unified mixed-mode client facade.
+ *
+ * Combines:
+ * - Gateway-routed tools (gateway_remote_mcp)
+ * - Direct internal MCP tools (internal_mcp_credentials)
+ *
+ * into a single tool listing/execution surface.
+ */
+
+interface KontextOrchestratorConfig {
+    clientId: string;
+    redirectUri: string;
+    serverUrl?: string;
+    storage?: KontextStorage;
+    sessionKey?: string;
+    onAuthRequired: KontextClientConfig["onAuthRequired"];
+    onIntegrationRequired?: KontextClientConfig["onIntegrationRequired"];
+    onStateChange?: (state: KontextOrchestratorState) => void;
+}
+interface KontextOrchestrator {
+    readonly state: KontextOrchestratorState;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    getConnectPageUrl(): Promise<ConnectSessionResult>;
+    readonly auth: {
+        signIn(): Promise<void>;
+        signOut(): Promise<void>;
+        handleCallback(url: string | URL): Promise<void>;
+        isCallback(url: string | URL): boolean;
+        readonly isAuthenticated: boolean;
+    };
+    readonly integrations: {
+        list(): Promise<IntegrationInfo[]>;
+    };
+    readonly tools: {
+        list(options?: {
+            limit?: number;
+        }): Promise<KontextTool[]>;
+        execute(toolId: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    };
+    on(event: "stateChange", handler: (state: KontextOrchestratorState) => void): () => void;
+    on(event: "error", handler: (error: KontextError) => void): () => void;
+    readonly mcp: KontextClient["mcp"];
+}
+declare function createKontextOrchestrator(config: KontextOrchestratorConfig): KontextOrchestrator;
+
+export { type KontextOrchestrator as K, type KontextOrchestratorConfig as a, type KontextOrchestratorState as b, createKontextOrchestrator as c };