@kontext-dev/js-sdk 0.1.0

package/dist/management/index.d.ts

@@ -0,0 +1,467 @@
+import { C as CreateServiceAccountInput, b as CreateServiceAccountResponse, P as PaginationParams, L as ListServiceAccountsResponse, S as ServiceAccountResponse, R as RotateSecretResponse, c as CreateApplicationInput, d as CreateApplicationResponse, e as ListApplicationsResponse, A as ApplicationResponse, U as UpdateApplicationInput, f as ApplicationOAuthResponse, g as UpdateApplicationOAuthInput, h as RotateApplicationSecretResponse, i as ApplicationIntegrationsResponse, j as UpdateApplicationIntegrationsInput, k as RevokeAllSessionsResponse, l as CreateIntegrationInput, m as CreateIntegrationResponse, n as ListIntegrationsResponse, I as IntegrationResponse, o as UpdateIntegrationInput, V as ValidateIntegrationResponse, p as ListAgentSessionsResponse, q as AgentSessionResponse, M as McpEventListResponse, r as ListTracesResponse, s as TraceResponse, t as TraceStatsResponse, K as KontextManagementClientConfig } from '../types-CzhnlJHW.js';
+export { u as AddUserTokenInput, v as AgentSession, w as AgentSessionDerivedStatus, x as AgentSessionStatus, y as Application, z as ApplicationOAuth, B as ConnectionResponse, D as ConnectionStatus, E as ConnectionStatusResponse, F as CreateApplicationOAuthInput, G as Integration, H as IntegrationAuthMode, J as IntegrationCapabilities, N as IntegrationOAuthConfigInput, O as IntegrationOAuthSummary, Q as IntegrationValidationStatus, W as ListEventsResponse, X as McpEvent, Y as OAuthTokens, Z as ServiceAccount, _ as TOKEN_EXCHANGE_GRANT_TYPE, $ as TOKEN_TYPE_ACCESS_TOKEN, T as TokenExchangeRequest, a as TokenExchangeResponse, a0 as Trace, a1 as TraceEvent, a2 as TraceStats } from '../types-CzhnlJHW.js';
+
+/**
+ * Service account authentication using OAuth 2.0 client_credentials flow
+ */
+interface ServiceAccountCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+interface AccessToken {
+    accessToken: string;
+    tokenType: string;
+    expiresAt: Date | null;
+    scope?: string;
+}
+/**
+ * Authenticates using the OAuth 2.0 client_credentials grant
+ * @param tokenUrl The token endpoint URL
+ * @param credentials Service account client credentials
+ * @param scopes Optional scopes to request
+ * @param audience Optional audience for the token
+ * @returns Access token response
+ */
+declare function authenticateServiceAccount(tokenUrl: string, credentials: ServiceAccountCredentials, scopes?: string[], audience?: string): Promise<AccessToken>;
+/**
+ * Token manager for automatic token refresh
+ */
+declare class TokenManager {
+    private readonly tokenUrl;
+    private readonly credentials;
+    private readonly scopes?;
+    private readonly audience?;
+    private token;
+    private tokenPromise;
+    private readonly bufferSeconds;
+    constructor(tokenUrl: string, credentials: ServiceAccountCredentials, scopes?: string[] | undefined, audience?: string | undefined);
+    /**
+     * Get a valid access token, refreshing if necessary
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Force a token refresh
+     */
+    refresh(): Promise<AccessToken>;
+    /**
+     * Clear the cached token
+     */
+    clear(): void;
+    private isExpired;
+}
+
+/**
+ * HTTP client utilities for the Management API
+ */
+
+interface HttpClientConfig {
+    baseUrl: string;
+    apiVersion: string;
+    tokenManager: TokenManager;
+}
+/**
+ * Internal HTTP client for making authenticated API requests
+ */
+declare class HttpClient {
+    private readonly config;
+    private readonly baseUrl;
+    constructor(config: HttpClientConfig);
+    /**
+     * Make a GET request
+     */
+    get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
+    /**
+     * Make a POST request
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Make a POST request without expecting a response body
+     */
+    postNoContent(path: string, body?: unknown): Promise<void>;
+    /**
+     * Make a PUT request
+     */
+    put<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Make a PATCH request
+     */
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Make a DELETE request
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Make a DELETE request expecting a response body
+     */
+    deleteJson<T>(path: string): Promise<T>;
+    private buildUrl;
+    private request;
+}
+
+/**
+ * Service Accounts resource methods
+ */
+
+/**
+ * Service Accounts API methods
+ */
+declare class ServiceAccountsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new service account
+     * @param input Service account creation parameters
+     * @returns The created service account with credentials
+     */
+    create(input: CreateServiceAccountInput): Promise<CreateServiceAccountResponse>;
+    /**
+     * List all service accounts
+     * @param pagination Optional pagination parameters
+     * @returns List of service accounts
+     */
+    list(pagination?: PaginationParams): Promise<ListServiceAccountsResponse>;
+    /**
+     * Get a service account by ID
+     * @param id Service account ID
+     * @returns The service account
+     */
+    get(id: string): Promise<ServiceAccountResponse>;
+    /**
+     * Rotate a service account's client secret
+     * @param id Service account ID
+     * @returns New credentials
+     */
+    rotateSecret(id: string): Promise<RotateSecretResponse>;
+    /**
+     * Revoke (delete) a service account
+     * @param id Service account ID
+     */
+    revoke(id: string): Promise<void>;
+}
+
+/**
+ * Applications resource methods
+ */
+
+/**
+ * Applications API methods
+ */
+declare class ApplicationsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new application
+     * @param input Application creation parameters
+     * @returns The created application with OAuth config
+     */
+    create(input: CreateApplicationInput): Promise<CreateApplicationResponse>;
+    /**
+     * List all applications
+     * @param pagination Optional pagination parameters
+     * @returns List of applications
+     */
+    list(pagination?: PaginationParams): Promise<ListApplicationsResponse>;
+    /**
+     * Get an application by ID
+     * @param id Application ID
+     * @returns The application
+     */
+    get(id: string): Promise<ApplicationResponse>;
+    /**
+     * Update an application
+     * @param id Application ID
+     * @param input Update parameters
+     * @returns The updated application
+     */
+    update(id: string, input: UpdateApplicationInput): Promise<ApplicationResponse>;
+    /**
+     * Archive an application (soft delete)
+     * @param id Application ID
+     */
+    archive(id: string): Promise<void>;
+    /**
+     * Get an application's OAuth configuration
+     * @param id Application ID
+     * @returns The OAuth configuration
+     */
+    getOAuth(id: string): Promise<ApplicationOAuthResponse>;
+    /**
+     * Update an application's OAuth configuration
+     * @param id Application ID
+     * @param input OAuth update parameters
+     * @returns The updated OAuth configuration
+     */
+    updateOAuth(id: string, input: UpdateApplicationOAuthInput): Promise<ApplicationOAuthResponse>;
+    /**
+     * Rotate an application's client secret (confidential clients only)
+     * @param id Application ID
+     * @returns The new OAuth configuration with new secret
+     */
+    rotateSecret(id: string): Promise<RotateApplicationSecretResponse>;
+    /**
+     * List integrations attached to an application
+     * @param id Application ID
+     * @returns List of integration IDs
+     */
+    listIntegrations(id: string): Promise<ApplicationIntegrationsResponse>;
+    /**
+     * 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
+     */
+    setIntegrations(id: string, input: UpdateApplicationIntegrationsInput): Promise<ApplicationIntegrationsResponse>;
+    /**
+     * Attach a single integration to an application
+     * @param id Application ID
+     * @param integrationId Integration ID to attach
+     */
+    attachIntegration(id: string, integrationId: string): Promise<void>;
+    /**
+     * Detach a single integration from an application
+     * @param id Application ID
+     * @param integrationId Integration ID to detach
+     */
+    detachIntegration(id: string, integrationId: string): Promise<void>;
+    /**
+     * Revoke all agent sessions for an application
+     * @param id Application ID
+     */
+    revokeAllAgentSessions(id: string): Promise<RevokeAllSessionsResponse>;
+}
+
+/**
+ * Integrations resource methods
+ */
+
+/**
+ * Integrations API methods
+ */
+declare class IntegrationsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create a new integration
+     * @param input Integration creation parameters
+     * @returns The created integration
+     */
+    create(input: CreateIntegrationInput): Promise<CreateIntegrationResponse>;
+    /**
+     * List all integrations
+     * @param pagination Optional pagination parameters
+     * @returns List of integrations
+     */
+    list(pagination?: PaginationParams): Promise<ListIntegrationsResponse>;
+    /**
+     * Get an integration by ID
+     * @param id Integration ID
+     * @returns The integration
+     */
+    get(id: string): Promise<IntegrationResponse>;
+    /**
+     * Update an integration
+     * @param id Integration ID
+     * @param input Update parameters
+     * @returns The updated integration
+     */
+    update(id: string, input: UpdateIntegrationInput): Promise<IntegrationResponse>;
+    /**
+     * Archive an integration (soft delete)
+     * @param id Integration ID
+     */
+    archive(id: string): Promise<void>;
+    /**
+     * Validate an integration (test connectivity)
+     * @param id Integration ID
+     * @returns Validation result
+     */
+    validate(id: string): Promise<ValidateIntegrationResponse>;
+}
+
+/**
+ * Agent Sessions resource methods
+ */
+
+interface ListAgentSessionsParams {
+    /** Include inactive sessions (disconnected/expired) */
+    includeInactive?: boolean;
+    /** Filter by status; "all" or "inactive" enables includeInactive */
+    status?: "active" | "inactive" | "all";
+    /** Limit number of sessions returned */
+    limit?: number;
+}
+/**
+ * Agent Sessions API methods
+ */
+declare class AgentSessionsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List all agent sessions
+     * @param params Optional filter and pagination parameters
+     * @returns List of agent sessions
+     */
+    list(applicationId: string, params?: ListAgentSessionsParams): Promise<ListAgentSessionsResponse>;
+    /**
+     * Get an agent session by ID
+     * @param id Agent session ID
+     * @returns The agent session
+     */
+    get(applicationId: string, sessionId: string): Promise<AgentSessionResponse>;
+    /**
+     * Revoke all sessions for an application
+     */
+    revokeAll(applicationId: string): Promise<RevokeAllSessionsResponse>;
+}
+
+/**
+ * Traces and Events resource methods
+ */
+
+interface ListTracesParams extends PaginationParams {
+    /** Filter by owner user ID (admin/owner only) */
+    userId?: string;
+    /** Filter by agent/application ID */
+    agentId?: string;
+    /** Filter by application ID (legacy alias for agentId) */
+    applicationId?: string;
+    /** Filter by agent session ID */
+    sessionId?: string;
+    /** Offset for pagination */
+    offset?: number;
+    /** @deprecated No longer supported by the API */
+    startAfter?: string;
+    /** @deprecated No longer supported by the API */
+    startBefore?: string;
+}
+interface ListEventsParams extends PaginationParams {
+    /** Maximum number of events to return (default: 100, max: 200) */
+    limit?: number;
+}
+interface TraceStatsParams {
+    /** Period window ("1d", "7d", "30d") */
+    period?: string;
+    /** Filter by owner user ID (admin/owner only) */
+    userId?: string;
+    /** @deprecated No longer supported by the API */
+    applicationId?: string;
+    /** @deprecated Legacy input; mapped to period when possible */
+    startTime?: string;
+    /** @deprecated Legacy input; currently unused */
+    endTime?: string;
+}
+/**
+ * Traces API methods
+ */
+declare class TracesResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List traces
+     * @param params Optional filter and pagination parameters
+     * @returns List of traces
+     */
+    list(params?: ListTracesParams): Promise<ListTracesResponse>;
+    /**
+     * Get a trace by ID with its events
+     * @param id Trace ID
+     * @returns The trace with events
+     */
+    get(id: string, params?: {
+        userId?: string;
+    }): Promise<TraceResponse>;
+    /**
+     * Get trace statistics
+     * @param params Optional filter parameters
+     * @returns Trace statistics
+     */
+    stats(params?: TraceStatsParams): Promise<TraceStatsResponse>;
+}
+/**
+ * Events API methods
+ */
+declare class EventsResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * List events
+     * @param params Optional filter and pagination parameters
+     * @returns List of events
+     */
+    list(params?: ListEventsParams): Promise<McpEventListResponse>;
+}
+
+/**
+ * KontextManagementClient - Control plane client for administrative operations
+ */
+
+/**
+ * Management API client for Kontext
+ *
+ * Use this client for administrative operations like:
+ * - Creating and managing service accounts
+ * - Creating and configuring applications
+ * - Managing integrations
+ * - Viewing agent sessions and traces
+ *
+ * @example
+ * ```typescript
+ * const client = new KontextManagementClient({
+ *   baseUrl: 'https://api.kontext.dev',
+ *   credentials: {
+ *     clientId: 'your-service-account-client-id',
+ *     clientSecret: 'your-service-account-client-secret',
+ *   },
+ * });
+ *
+ * // Create an application
+ * const { application, oauth } = await client.applications.create({
+ *   name: 'My Agent',
+ *   oauth: {
+ *     redirectUris: ['http://localhost:3000/callback'],
+ *   },
+ * });
+ *
+ * // Create an integration
+ * const { integration } = await client.integrations.create({
+ *   name: 'GitHub',
+ *   url: 'https://mcp.github.com/sse',
+ *   authMode: 'oauth',
+ *   oauth: { provider: 'github' },
+ * });
+ *
+ * // Attach integration to application
+ * await client.applications.attachIntegration(application.id, integration.id);
+ * ```
+ */
+declare class KontextManagementClient {
+    private readonly tokenManager;
+    private readonly http;
+    /** Service Accounts resource */
+    readonly serviceAccounts: ServiceAccountsResource;
+    /** Applications resource */
+    readonly applications: ApplicationsResource;
+    /** Integrations resource */
+    readonly integrations: IntegrationsResource;
+    /** Agent Sessions resource (alias: agentInstances) */
+    readonly agentSessions: AgentSessionsResource;
+    /** Agent Instances resource (alias for agentSessions, future naming) */
+    readonly agentInstances: AgentSessionsResource;
+    /** Traces resource */
+    readonly traces: TracesResource;
+    /** Events resource */
+    readonly events: EventsResource;
+    constructor(config: KontextManagementClientConfig);
+    /**
+     * Force refresh the access token
+     * Useful if you need to ensure a fresh token before a critical operation
+     */
+    refreshToken(): Promise<void>;
+    /**
+     * Clear the cached access token
+     * Useful when credentials have been rotated
+     */
+    clearToken(): void;
+}
+
+export { type AccessToken, AgentSessionResponse, AgentSessionsResource, ApplicationIntegrationsResponse, ApplicationOAuthResponse, ApplicationResponse, ApplicationsResource, CreateApplicationInput, CreateApplicationResponse, CreateIntegrationInput, CreateIntegrationResponse, CreateServiceAccountInput, CreateServiceAccountResponse, EventsResource, IntegrationResponse, IntegrationsResource, KontextManagementClient, KontextManagementClientConfig, type ListAgentSessionsParams, ListAgentSessionsResponse, ListApplicationsResponse, type ListEventsParams, ListIntegrationsResponse, ListServiceAccountsResponse, type ListTracesParams, ListTracesResponse, McpEventListResponse, PaginationParams, RevokeAllSessionsResponse, RotateApplicationSecretResponse, RotateSecretResponse, type ServiceAccountCredentials, ServiceAccountResponse, ServiceAccountsResource, TokenManager, TraceResponse, type TraceStatsParams, TraceStatsResponse, TracesResource, UpdateApplicationInput, UpdateApplicationIntegrationsInput, UpdateApplicationOAuthInput, UpdateIntegrationInput, ValidateIntegrationResponse, authenticateServiceAccount };