@kontext-dev/js-sdk 0.1.0

package/dist/management/index.js

@@ -0,0 +1,855 @@
+// 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");
+  }
+};
+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 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 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
+      });
+  }
+}
+
+// src/management/auth.ts
+async function authenticateServiceAccount(tokenUrl, credentials, scopes, audience) {
+  const params = new URLSearchParams({
+    grant_type: "client_credentials"
+  });
+  if (scopes && scopes.length > 0) {
+    params.set("scope", scopes.join(" "));
+  }
+  if (audience) {
+    params.set("audience", audience);
+  }
+  const basicAuth = Buffer.from(
+    `${credentials.clientId}:${credentials.clientSecret}`
+  ).toString("base64");
+  let response;
+  try {
+    response = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+        Authorization: `Basic ${basicAuth}`
+      },
+      body: params.toString()
+    });
+  } catch (err) {
+    throw new NetworkError("Failed to connect to token endpoint", {
+      cause: err instanceof Error ? err : void 0
+    });
+  }
+  if (!response.ok) {
+    let errorBody;
+    try {
+      errorBody = await response.json();
+    } catch {
+      errorBody = await response.text();
+    }
+    if (response.status === 401) {
+      throw new AuthorizationRequiredError(
+        "Invalid service account credentials"
+      );
+    }
+    const errorCode = typeof errorBody === "object" && errorBody !== null && "error" in errorBody ? String(errorBody.error) : "unknown_error";
+    const errorDescription = typeof errorBody === "object" && errorBody !== null && "error_description" in errorBody ? String(
+      errorBody.error_description
+    ) : void 0;
+    throw new OAuthError(
+      errorDescription ?? `Token request failed: ${errorCode}`,
+      "kontext_oauth_token_exchange_failed",
+      { errorCode, errorDescription }
+    );
+  }
+  const tokenData = await response.json();
+  return {
+    accessToken: tokenData.access_token,
+    tokenType: tokenData.token_type,
+    expiresAt: tokenData.expires_in ? new Date(Date.now() + tokenData.expires_in * 1e3) : null,
+    scope: tokenData.scope
+  };
+}
+var TokenManager = class {
+  // Refresh 60 seconds before expiry
+  constructor(tokenUrl, credentials, scopes, audience) {
+    this.tokenUrl = tokenUrl;
+    this.credentials = credentials;
+    this.scopes = scopes;
+    this.audience = audience;
+  }
+  token = null;
+  tokenPromise = null;
+  bufferSeconds = 60;
+  /**
+   * Get a valid access token, refreshing if necessary
+   */
+  async getAccessToken() {
+    if (this.token && !this.isExpired(this.token)) {
+      return this.token.accessToken;
+    }
+    if (!this.tokenPromise) {
+      this.tokenPromise = this.refresh().finally(() => {
+        this.tokenPromise = null;
+      });
+    }
+    const token = await this.tokenPromise;
+    return token.accessToken;
+  }
+  /**
+   * Force a token refresh
+   */
+  async refresh() {
+    this.token = await authenticateServiceAccount(
+      this.tokenUrl,
+      this.credentials,
+      this.scopes,
+      this.audience
+    );
+    return this.token;
+  }
+  /**
+   * Clear the cached token
+   */
+  clear() {
+    this.token = null;
+    this.tokenPromise = null;
+  }
+  isExpired(token) {
+    if (!token.expiresAt) {
+      return false;
+    }
+    const bufferMs = this.bufferSeconds * 1e3;
+    return Date.now() >= token.expiresAt.getTime() - bufferMs;
+  }
+};
+
+// src/management/http.ts
+var HttpClient = class {
+  constructor(config) {
+    this.config = config;
+    this.baseUrl = `${config.baseUrl.replace(/\/$/, "")}/api/${config.apiVersion}`;
+  }
+  baseUrl;
+  /**
+   * Make a GET request
+   */
+  async get(path, params) {
+    const url = this.buildUrl(path, params);
+    return this.request("GET", url, void 0, true);
+  }
+  /**
+   * Make a POST request
+   */
+  async post(path, body) {
+    const url = this.buildUrl(path);
+    return this.request("POST", url, body, true);
+  }
+  /**
+   * Make a POST request without expecting a response body
+   */
+  async postNoContent(path, body) {
+    const url = this.buildUrl(path);
+    await this.request("POST", url, body, false);
+  }
+  /**
+   * Make a PUT request
+   */
+  async put(path, body) {
+    const url = this.buildUrl(path);
+    return this.request("PUT", url, body, true);
+  }
+  /**
+   * Make a PATCH request
+   */
+  async patch(path, body) {
+    const url = this.buildUrl(path);
+    return this.request("PATCH", url, body, true);
+  }
+  /**
+   * Make a DELETE request
+   */
+  async delete(path) {
+    const url = this.buildUrl(path);
+    await this.request("DELETE", url, void 0, false);
+  }
+  /**
+   * Make a DELETE request expecting a response body
+   */
+  async deleteJson(path) {
+    const url = this.buildUrl(path);
+    return this.request("DELETE", url, void 0, true);
+  }
+  buildUrl(path, params) {
+    const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+    const url = new URL(normalizedPath, this.baseUrl + "/");
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return url.toString();
+  }
+  async request(method, url, body, expectBody) {
+    const accessToken = await this.config.tokenManager.getAccessToken();
+    const headers = {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: "application/json"
+    };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+    }
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body: body !== void 0 ? JSON.stringify(body) : void 0
+      });
+    } catch (err) {
+      throw new NetworkError(`Request to ${url} failed`, {
+        cause: err instanceof Error ? err : void 0
+      });
+    }
+    if (response.status === 204) {
+      if (expectBody) {
+        throw new NetworkError(
+          `Expected response body but got 204 from ${url}`
+        );
+      }
+      return;
+    }
+    let responseBody;
+    if (expectBody || !response.ok) {
+      const contentType = response.headers.get("content-type");
+      if (contentType?.includes("application/json")) {
+        try {
+          responseBody = await response.json();
+        } catch {
+          responseBody = void 0;
+        }
+      } else {
+        responseBody = await response.text();
+      }
+    }
+    if (!response.ok) {
+      throw parseHttpError(response.status, responseBody);
+    }
+    if (!expectBody) {
+      return;
+    }
+    return responseBody;
+  }
+};
+function paginationToParams(pagination) {
+  return {
+    cursor: pagination?.cursor,
+    limit: pagination?.limit
+  };
+}
+
+// src/management/service-accounts.ts
+var ServiceAccountsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new service account
+   * @param input Service account creation parameters
+   * @returns The created service account with credentials
+   */
+  async create(input) {
+    return this.http.post(
+      "/service-accounts",
+      input
+    );
+  }
+  /**
+   * List all service accounts
+   * @param pagination Optional pagination parameters
+   * @returns List of service accounts
+   */
+  async list(pagination) {
+    return this.http.get(
+      "/service-accounts",
+      paginationToParams(pagination)
+    );
+  }
+  /**
+   * Get a service account by ID
+   * @param id Service account ID
+   * @returns The service account
+   */
+  async get(id) {
+    return this.http.get(`/service-accounts/${id}`);
+  }
+  /**
+   * Rotate a service account's client secret
+   * @param id Service account ID
+   * @returns New credentials
+   */
+  async rotateSecret(id) {
+    return this.http.post(
+      `/service-accounts/${id}/rotate-secret`
+    );
+  }
+  /**
+   * Revoke (delete) a service account
+   * @param id Service account ID
+   */
+  async revoke(id) {
+    await this.http.delete(`/service-accounts/${id}`);
+  }
+};
+
+// src/management/applications.ts
+var ApplicationsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new application
+   * @param input Application creation parameters
+   * @returns The created application with OAuth config
+   */
+  async create(input) {
+    return this.http.post("/applications", input);
+  }
+  /**
+   * List all applications
+   * @param pagination Optional pagination parameters
+   * @returns List of applications
+   */
+  async list(pagination) {
+    return this.http.get(
+      "/applications",
+      paginationToParams(pagination)
+    );
+  }
+  /**
+   * Get an application by ID
+   * @param id Application ID
+   * @returns The application
+   */
+  async get(id) {
+    return this.http.get(`/applications/${id}`);
+  }
+  /**
+   * Update an application
+   * @param id Application ID
+   * @param input Update parameters
+   * @returns The updated application
+   */
+  async update(id, input) {
+    return this.http.patch(`/applications/${id}`, input);
+  }
+  /**
+   * Archive an application (soft delete)
+   * @param id Application ID
+   */
+  async archive(id) {
+    await this.http.delete(`/applications/${id}`);
+  }
+  /**
+   * Get an application's OAuth configuration
+   * @param id Application ID
+   * @returns The OAuth configuration
+   */
+  async getOAuth(id) {
+    return this.http.get(`/applications/${id}/oauth`);
+  }
+  /**
+   * Update an application's OAuth configuration
+   * @param id Application ID
+   * @param input OAuth update parameters
+   * @returns The updated OAuth configuration
+   */
+  async updateOAuth(id, input) {
+    return this.http.patch(
+      `/applications/${id}/oauth`,
+      input
+    );
+  }
+  /**
+   * Rotate an application's client secret (confidential clients only)
+   * @param id Application ID
+   * @returns The new OAuth configuration with new secret
+   */
+  async rotateSecret(id) {
+    return this.http.post(
+      `/applications/${id}/rotate-secret`
+    );
+  }
+  /**
+   * List integrations attached to an application
+   * @param id Application ID
+   * @returns List of integration IDs
+   */
+  async listIntegrations(id) {
+    return this.http.get(
+      `/applications/${id}/integrations`
+    );
+  }
+  /**
+   * Set the integrations attached to an application (replaces all)
+   * @param id Application ID
+   * @param input Integration IDs to attach
+   * @returns Updated list of integration IDs
+   */
+  async setIntegrations(id, input) {
+    return this.http.put(
+      `/applications/${id}/integrations`,
+      input
+    );
+  }
+  /**
+   * Attach a single integration to an application
+   * @param id Application ID
+   * @param integrationId Integration ID to attach
+   */
+  async attachIntegration(id, integrationId) {
+    await this.http.postNoContent(
+      `/applications/${id}/integrations/${integrationId}`
+    );
+  }
+  /**
+   * Detach a single integration from an application
+   * @param id Application ID
+   * @param integrationId Integration ID to detach
+   */
+  async detachIntegration(id, integrationId) {
+    await this.http.delete(`/applications/${id}/integrations/${integrationId}`);
+  }
+  /**
+   * Revoke all agent sessions for an application
+   * @param id Application ID
+   */
+  async revokeAllAgentSessions(id) {
+    return this.http.deleteJson(
+      `/applications/${id}/sessions`
+    );
+  }
+};
+
+// src/management/integrations.ts
+var IntegrationsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a new integration
+   * @param input Integration creation parameters
+   * @returns The created integration
+   */
+  async create(input) {
+    return this.http.post("/integrations", input);
+  }
+  /**
+   * List all integrations
+   * @param pagination Optional pagination parameters
+   * @returns List of integrations
+   */
+  async list(pagination) {
+    return this.http.get(
+      "/integrations",
+      paginationToParams(pagination)
+    );
+  }
+  /**
+   * Get an integration by ID
+   * @param id Integration ID
+   * @returns The integration
+   */
+  async get(id) {
+    return this.http.get(`/integrations/${id}`);
+  }
+  /**
+   * Update an integration
+   * @param id Integration ID
+   * @param input Update parameters
+   * @returns The updated integration
+   */
+  async update(id, input) {
+    return this.http.patch(`/integrations/${id}`, input);
+  }
+  /**
+   * Archive an integration (soft delete)
+   * @param id Integration ID
+   */
+  async archive(id) {
+    await this.http.delete(`/integrations/${id}`);
+  }
+  /**
+   * Validate an integration (test connectivity)
+   * @param id Integration ID
+   * @returns Validation result
+   */
+  async validate(id) {
+    return this.http.post(
+      `/integrations/${id}/validate`
+    );
+  }
+};
+
+// src/management/agent-sessions.ts
+var AgentSessionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List all agent sessions
+   * @param params Optional filter and pagination parameters
+   * @returns List of agent sessions
+   */
+  async list(applicationId, params) {
+    return this.http.get(
+      `/applications/${applicationId}/sessions`,
+      {
+        status: params?.status,
+        includeInactive: params?.includeInactive ? "true" : void 0,
+        limit: params?.limit
+      }
+    );
+  }
+  /**
+   * Get an agent session by ID
+   * @param id Agent session ID
+   * @returns The agent session
+   */
+  async get(applicationId, sessionId) {
+    return this.http.get(
+      `/applications/${applicationId}/sessions/${sessionId}`
+    );
+  }
+  /**
+   * Revoke all sessions for an application
+   */
+  async revokeAll(applicationId) {
+    return this.http.deleteJson(
+      `/applications/${applicationId}/sessions`
+    );
+  }
+};
+
+// src/management/traces.ts
+var TracesResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List traces
+   * @param params Optional filter and pagination parameters
+   * @returns List of traces
+   */
+  async list(params) {
+    const agentId = params?.agentId ?? params?.applicationId;
+    const offsetFromCursor = params?.cursor && !Number.isNaN(Number(params.cursor)) ? Number(params.cursor) : void 0;
+    return this.http.get("/traces", {
+      limit: params?.limit,
+      offset: params?.offset ?? offsetFromCursor,
+      userId: params?.userId,
+      sessionId: params?.sessionId,
+      agentId
+    });
+  }
+  /**
+   * Get a trace by ID with its events
+   * @param id Trace ID
+   * @returns The trace with events
+   */
+  async get(id, params) {
+    const response = await this.http.get(`/traces/${id}`, {
+      userId: params?.userId
+    });
+    if ("trace" in response && response.trace) {
+      return response;
+    }
+    const events = response.events ?? [];
+    const first = events[0];
+    const last = events.length > 0 ? events[events.length - 1] : void 0;
+    const traceId = first?.traceId ?? id;
+    const sessionId = first?.sessionId ?? "";
+    const okCount = events.filter((event) => event.status === "ok").length;
+    const warnCount = events.filter((event) => event.status === "warn").length;
+    const errorCount = events.filter(
+      (event) => ["error_remote", "error_proxy", "error_auth", "error"].includes(
+        event.status
+      )
+    ).length;
+    return {
+      trace: {
+        traceId,
+        sessionId,
+        startedAt: first?.createdAt ?? null,
+        endedAt: last?.createdAt ?? null,
+        eventCount: events.length,
+        okCount,
+        warnCount,
+        errorCount,
+        agentId: first?.agentId,
+        agentSessionId: first?.agentSessionId ?? void 0
+      },
+      events
+    };
+  }
+  /**
+   * Get trace statistics
+   * @param params Optional filter parameters
+   * @returns Trace statistics
+   */
+  async stats(params) {
+    const period = params?.period ?? (params?.startTime ? inferPeriodFromStartTime(params.startTime) : void 0);
+    const response = await this.http.get("/traces/stats", {
+      period,
+      userId: params?.userId
+    });
+    if ("stats" in response) {
+      return response;
+    }
+    return { stats: response };
+  }
+};
+var EventsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * List events
+   * @param params Optional filter and pagination parameters
+   * @returns List of events
+   */
+  async list(params) {
+    return this.http.get("/mcp-events", {
+      limit: params?.limit
+    });
+  }
+};
+function inferPeriodFromStartTime(startTime) {
+  const startMs = Date.parse(startTime);
+  if (Number.isNaN(startMs)) {
+    return "7d";
+  }
+  const diffMs = Date.now() - startMs;
+  const diffDays = Math.ceil(diffMs / (24 * 60 * 60 * 1e3));
+  if (diffDays <= 1) return "1d";
+  if (diffDays <= 7) return "7d";
+  return "30d";
+}
+
+// src/management/client.ts
+var DEFAULT_API_VERSION = "v1";
+var KontextManagementClient = class {
+  tokenManager;
+  http;
+  /** Service Accounts resource */
+  serviceAccounts;
+  /** Applications resource */
+  applications;
+  /** Integrations resource */
+  integrations;
+  /** Agent Sessions resource (alias: agentInstances) */
+  agentSessions;
+  /** Agent Instances resource (alias for agentSessions, future naming) */
+  agentInstances;
+  /** Traces resource */
+  traces;
+  /** Events resource */
+  events;
+  constructor(config) {
+    const baseUrl = config.baseUrl.replace(/\/$/, "");
+    const apiVersion = config.apiVersion ?? DEFAULT_API_VERSION;
+    const tokenUrl = config.tokenUrl ?? `${baseUrl}/oauth2/token`;
+    const scopes = config.scopes ?? ["management:all"];
+    const audience = config.audience ?? `${baseUrl}/api/${apiVersion}`;
+    this.tokenManager = new TokenManager(
+      tokenUrl,
+      {
+        clientId: config.credentials.clientId,
+        clientSecret: config.credentials.clientSecret
+      },
+      scopes,
+      audience
+    );
+    this.http = new HttpClient({
+      baseUrl,
+      apiVersion,
+      tokenManager: this.tokenManager
+    });
+    this.serviceAccounts = new ServiceAccountsResource(this.http);
+    this.applications = new ApplicationsResource(this.http);
+    this.integrations = new IntegrationsResource(this.http);
+    this.agentSessions = new AgentSessionsResource(this.http);
+    this.agentInstances = this.agentSessions;
+    this.traces = new TracesResource(this.http);
+    this.events = new EventsResource(this.http);
+  }
+  /**
+   * Force refresh the access token
+   * Useful if you need to ensure a fresh token before a critical operation
+   */
+  async refreshToken() {
+    await this.tokenManager.refresh();
+  }
+  /**
+   * Clear the cached access token
+   * Useful when credentials have been rotated
+   */
+  clearToken() {
+    this.tokenManager.clear();
+  }
+};
+
+// 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";
+
+export { AgentSessionsResource, ApplicationsResource, EventsResource, IntegrationsResource, KontextManagementClient, ServiceAccountsResource, TOKEN_EXCHANGE_GRANT_TYPE, TOKEN_TYPE_ACCESS_TOKEN, TokenManager, TracesResource, authenticateServiceAccount };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map