@kontext-dev/js-sdk 0.3.0 → 1.1.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 export { ClientState, ConnectSessionResult, IntegrationInfo, KontextClient, KontextClientConfig, KontextTool, ToolResult, createKontextClient } from './client/index.cjs';
 export { K as KontextOrchestrator, a as KontextOrchestratorConfig, b as KontextOrchestratorState, c as createKontextOrchestrator } from './index-DcL4a5Vq.cjs';
-export { I as IntegrationCredential, a as IntegrationName, b as IntegrationResolvedCredentials, K as KnownIntegration, c as Kontext, d as KontextOptions, M as McpServerFactory, e as McpServerOrFactory, f as MiddlewareOptions } from './kontext-CgIBANFo.cjs';
+export { I as IntegrationCredential, a as IntegrationName, b as IntegrationResolvedCredentials, K as KnownIntegration, c as Kontext, d as KontextOptions, M as McpServerFactory, e as McpServerOrFactory, f as MiddlewareOptions } from './kontext-CBPuE-hq.cjs';
 export { K as KontextTokenVerifier, a as KontextTokenVerifierConfig } from './verifier-CoJmYiw3.cjs';
 export { AuthorizationRequiredError, ConfigError, ElicitationEntry, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError } from './errors.cjs';
 import './mcp/index.cjs';

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { ClientState, ConnectSessionResult, IntegrationInfo, KontextClient, KontextClientConfig, KontextTool, ToolResult, createKontextClient } from './client/index.js';
 export { K as KontextOrchestrator, a as KontextOrchestratorConfig, b as KontextOrchestratorState, c as createKontextOrchestrator } from './index-D5hS5PGn.js';
-export { I as IntegrationCredential, a as IntegrationName, b as IntegrationResolvedCredentials, K as KnownIntegration, c as Kontext, d as KontextOptions, M as McpServerFactory, e as McpServerOrFactory, f as MiddlewareOptions } from './kontext-CgIBANFo.js';
+export { I as IntegrationCredential, a as IntegrationName, b as IntegrationResolvedCredentials, K as KnownIntegration, c as Kontext, d as KontextOptions, M as McpServerFactory, e as McpServerOrFactory, f as MiddlewareOptions } from './kontext-CBPuE-hq.js';
 export { K as KontextTokenVerifier, a as KontextTokenVerifierConfig } from './verifier-CoJmYiw3.js';
 export { AuthorizationRequiredError, ConfigError, ElicitationEntry, HttpError, IntegrationConnectionRequiredError, KontextError, NetworkError, OAuthError, isKontextError, isNetworkError, isUnauthorizedError, parseHttpError } from './errors.js';
 import './mcp/index.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { isInitializeRequest, UrlElicitationRequiredError, ElicitRequestSchema, ElicitationCompleteNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { ErrorCode, isInitializeRequest, UrlElicitationRequiredError, ElicitRequestSchema, ElicitationCompleteNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
 import { createHash, randomBytes } from 'crypto';
 import { createRequire } from 'module';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -73,8 +73,6 @@ var StorageKeys = {
 function resourceTokenKey(resource) {
   return `${StorageKeys.RESOURCE_TOKENS}:${resource}`;
 }
-
-// src/errors.ts
 var KontextError = class extends Error {
   /** Brand field for type narrowing without instanceof */
   kontextError = true;
@@ -207,12 +205,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;
 }
@@ -271,6 +277,73 @@ 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
+  });
+}
 
 // src/oauth/provider.ts
 var KontextOAuthProvider = class {
@@ -708,7 +781,22 @@ var KontextMcp = class {
       const url = typeof item.url === "string" ? item.url : "";
       if (!id || !url) return null;
       const category = item.category === "internal_mcp_credentials" ? "internal_mcp_credentials" : "gateway_remote_mcp";
-      const connectType = item.connectType === "credentials" || item.connectType === "oauth" || item.connectType === "none" ? item.connectType : category === "internal_mcp_credentials" ? "credentials" : item.authMode === "oauth" ? "oauth" : "none";
+      const rawConnectType = item.connectType;
+      if (typeof rawConnectType !== "string") {
+        throw new KontextError(
+          "Runtime integration connectType is required in API response.",
+          "kontext_runtime_integrations_invalid_response",
+          { meta: { integrationId: id, connectType: rawConnectType } }
+        );
+      }
+      const connectType = rawConnectType === "credentials" || rawConnectType === "oauth" || rawConnectType === "user_token" || rawConnectType === "none" ? rawConnectType : null;
+      if (!connectType) {
+        throw new KontextError(
+          `Unknown runtime integration connectType "${rawConnectType}".`,
+          "kontext_runtime_integrations_invalid_response",
+          { meta: { integrationId: id, connectType: rawConnectType } }
+        );
+      }
       const rawConnection = item.connection && typeof item.connection === "object" ? item.connection : void 0;
       const connected = rawConnection && typeof rawConnection.connected === "boolean" ? rawConnection.connected : false;
       const status = rawConnection?.status === "connected" ? "connected" : "disconnected";
@@ -719,6 +807,9 @@ var KontextMcp = class {
         category,
         connectType,
         authMode: item.authMode === "oauth" || item.authMode === "user_token" || item.authMode === "server_token" || item.authMode === "none" ? item.authMode : void 0,
+        tokenLabel: typeof item.tokenLabel === "string" ? item.tokenLabel : void 0,
+        tokenHelpUrl: typeof item.tokenHelpUrl === "string" ? item.tokenHelpUrl : void 0,
+        tokenPlaceholder: typeof item.tokenPlaceholder === "string" ? item.tokenPlaceholder : void 0,
         credentialSchema: item.credentialSchema,
         requiresOauth: typeof item.requiresOauth === "boolean" ? item.requiresOauth : void 0,
         connection: rawConnection ? {
@@ -1420,35 +1511,21 @@ async function withTransientRetry(operation, maxRetries = 1) {
 function toKontextError(err, context) {
   const contextMeta = context ? { ...context } : void 0;
   const mergeMeta = (base) => contextMeta ? { ...base ?? {}, ...contextMeta } : base ?? {};
-  if (isKontextError(err)) {
-    if (!contextMeta) {
-      return err;
-    }
-    const cloned = Object.create(Object.getPrototypeOf(err));
-    Object.defineProperties(cloned, Object.getOwnPropertyDescriptors(err));
-    Object.defineProperty(cloned, "meta", {
-      value: mergeMeta(err.meta),
-      enumerable: true,
-      writable: true,
-      configurable: true
-    });
-    return cloned;
-  }
-  if (err instanceof Error) {
-    if (isUnauthorizedError(err)) {
-      return new AuthorizationRequiredError(err.message, {
-        meta: mergeMeta(),
-        cause: err
-      });
-    }
-    return new KontextError(err.message, "kontext_unknown_error", {
-      meta: mergeMeta(),
-      cause: err
-    });
+  const translated = translateError(err);
+  if (!contextMeta) {
+    return translated;
   }
-  return new KontextError(String(err), "kontext_unknown_error", {
-    meta: mergeMeta()
+  const cloned = Object.create(
+    Object.getPrototypeOf(translated)
+  );
+  Object.defineProperties(cloned, Object.getOwnPropertyDescriptors(translated));
+  Object.defineProperty(cloned, "meta", {
+    value: mergeMeta(translated.meta),
+    enumerable: true,
+    writable: true,
+    configurable: true
   });
+  return cloned;
 }
 function isAuthorizationRequired(err) {
   if (err instanceof AuthorizationRequiredError) return true;
@@ -2162,45 +2239,6 @@ function extractTextContent(result) {
   }
   return JSON.stringify(result);
 }
-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 === -32042) {
-    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
-      }
-    );
-  }
-  const statusCode = props.statusCode ?? props.status;
-  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
-  });
-}
 function createSingleEndpointKontextClient(config) {
   if (!config.clientId) {
     throw new ConfigError(
@@ -2490,6 +2528,7 @@ function createKontextClient(config) {
 // src/management/types.ts
 var TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
 var TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token";
+var TOKEN_TYPE_USER_ID = "urn:kontext:user-id";
 
 // src/oauth/token-exchange.ts
 async function exchangeToken(config, subjectToken, resource, scope, subjectTokenType = TOKEN_TYPE_ACCESS_TOKEN) {
@@ -2969,7 +3008,7 @@ var Kontext = class _Kontext {
   oauthMetadata = null;
   metadataFetchedAt = 0;
   metadataPromise = null;
-  // Token exchange caching: keyed by `${integration}\0${subjectToken}`
+  // Token exchange caching: keyed by `${mode}\0${integration}\0${subjectToken}`
   credentialCache = /* @__PURE__ */ new Map();
   resolvedCredentialCache = /* @__PURE__ */ new Map();
   runtimeAuthCache = /* @__PURE__ */ new Map();
@@ -3127,23 +3166,28 @@ var Kontext = class _Kontext {
     router.delete(mcpPath, mcpHandler.delete);
     return router;
   }
-  // ===========================================================================
-  // require()
-  // ===========================================================================
-  /**
-   * Exchange a user's access token for an integration credential.
-   *
-   * @param integration - Integration name (e.g., "github")
-   * @param token - The user's Bearer token (from `authInfo.token`)
-   * @returns Integration credential with `accessToken` and `authorization` header
-   *
-   * @throws {IntegrationConnectionRequiredError} User hasn't connected this integration
-   * @throws {OAuthError} Token exchange failed
-   */
-  async require(integration, token) {
+  async require(integration, tokenOrOpts) {
+    let isUserIdMode = false;
+    let subjectToken = "";
+    if (typeof tokenOrOpts === "string") {
+      subjectToken = tokenOrOpts;
+    } else if (tokenOrOpts !== null && typeof tokenOrOpts === "object" && typeof tokenOrOpts.userId === "string") {
+      isUserIdMode = true;
+      subjectToken = tokenOrOpts.userId.trim();
+      if (!subjectToken) {
+        throw new TypeError(
+          "Kontext.require() expects a non-empty userId when called with { userId }."
+        );
+      }
+    } else {
+      throw new TypeError(
+        "Kontext.require() expects a token string or { userId: string }."
+      );
+    }
+    const subjectTokenType = isUserIdMode ? TOKEN_TYPE_USER_ID : void 0;
     const now = Date.now();
     this.evictExpiredCredentials(now);
-    const cacheKey = `${integration}\0${token}`;
+    const cacheKey = isUserIdMode ? `u\0${integration}\0${subjectToken}` : `t\0${integration}\0${subjectToken}`;
     const cached = this.credentialCache.get(cacheKey);
     if (cached && now < cached.expiresAt) {
       this.credentialCache.delete(cacheKey);
@@ -3160,13 +3204,25 @@ var Kontext = class _Kontext {
     };
     let response;
     try {
-      response = await exchangeToken(exchangeConfig, token, integration);
+      response = await exchangeToken(
+        exchangeConfig,
+        subjectToken,
+        integration,
+        void 0,
+        subjectTokenType
+      );
     } catch (err) {
       if (err instanceof OAuthError) {
         if (err.errorCode === "integration_required" || err.message.includes("not connected") || err.message.includes("expired") && err.message.includes("reconnect")) {
           const integrationId = err.meta.integrationId || integration;
+          if (isUserIdMode) {
+            throw new IntegrationConnectionRequiredError(integrationId, {
+              integrationName: err.meta.integrationName,
+              message: err.message
+            });
+          }
           const connectUrl = await this.fetchConnectUrl(
-            token,
+            subjectToken,
             integrationId,
             exchangeConfig
           );
@@ -3677,6 +3733,12 @@ var Kontext = class _Kontext {
   // ===========================================================================
   createAgentSession(userToken, mcpSessionId, metadata) {
     if (!this.clientSecret || !userToken) return;
+    if (!metadata?.authenticatedUserId) {
+      console.warn(
+        "[kontext:sessions] create skipped: missing authenticated user id"
+      );
+      return;
+    }
     const tokenIdentifier = createHash("sha256").update(userToken).digest("hex");
     this.getServiceToken().then(
       (token) => fetch(`${this.apiUrl}/api/v1/agent-sessions`, {
@@ -3687,6 +3749,7 @@ var Kontext = class _Kontext {
         },
         body: JSON.stringify({
           tokenIdentifier,
+          authenticatedUserId: metadata.authenticatedUserId,
           clientSessionId: mcpSessionId,
           hostname: metadata?.hostname,
           userAgent: metadata?.userAgent,
@@ -3908,6 +3971,7 @@ var Kontext = class _Kontext {
             status: "ok"
           });
           this.createAgentSession(authInfo?.token, sid, {
+            authenticatedUserId: typeof authInfo?.extra?.sub === "string" ? authInfo.extra.sub : void 0,
             hostname: req.headers["x-forwarded-for"],
             userAgent: req.headers["user-agent"],
             tokenExpiresAt: authInfo?.expiresAt