@kontext-dev/js-sdk 0.1.0

package/dist/types-CzhnlJHW.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Core types for the Kontext SDK
+ * These mirror the API DTOs for type-safe interactions
+ */
+interface Application {
+    id: string;
+    name: string;
+    canModify?: boolean;
+    activeSessionCount?: number;
+    idleSessionCount?: number;
+    liveSessionCount?: number;
+    totalSessionCount?: number;
+    oauth?: ApplicationOAuth;
+    archivedAt?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ApplicationOAuth {
+    type: "public" | "confidential";
+    clientId: string;
+    clientSecret?: string;
+    pkceRequired: boolean;
+    scopes: string[];
+    authorizationUrl: string;
+    tokenUrl: string;
+    gatewayUrl: string;
+    redirectUris: string[];
+}
+interface CreateApplicationOAuthInput {
+    type?: "public" | "confidential";
+    redirectUris: string[];
+    pkceRequired?: boolean;
+    scopes?: string[];
+}
+interface CreateApplicationInput {
+    name: string;
+    oauth: CreateApplicationOAuthInput;
+}
+interface UpdateApplicationInput {
+    name?: string;
+}
+interface UpdateApplicationOAuthInput {
+    pkceRequired?: boolean;
+    scopes?: string[];
+    redirectUris?: string[];
+}
+interface CreateApplicationResponse {
+    application: Application;
+    oauth: ApplicationOAuth;
+}
+interface ApplicationResponse {
+    application: Application;
+}
+interface ApplicationOAuthResponse {
+    oauth: ApplicationOAuth;
+}
+interface ListApplicationsResponse {
+    items: Application[];
+    nextCursor?: string;
+}
+interface RotateApplicationSecretResponse {
+    oauth: ApplicationOAuth;
+}
+interface UpdateApplicationIntegrationsInput {
+    integrationIds: string[];
+}
+interface ApplicationIntegrationsResponse {
+    integrationIds: string[];
+}
+type IntegrationAuthMode = "oauth" | "user_token" | "server_token" | "none";
+type IntegrationValidationStatus = "pending" | "valid" | "invalid";
+interface IntegrationOAuthSummary {
+    provider?: string;
+    issuer?: string;
+    scopes?: string[];
+    metadata?: Record<string, unknown>;
+}
+interface IntegrationCapabilities {
+    tools?: boolean;
+    resources?: boolean;
+    prompts?: boolean;
+}
+interface Integration {
+    id: string;
+    name: string;
+    url: string;
+    authMode: IntegrationAuthMode;
+    oauth?: IntegrationOAuthSummary;
+    capabilities?: IntegrationCapabilities;
+    serverTokenConfigured: boolean;
+    validationStatus: IntegrationValidationStatus;
+    validationMessage?: string;
+    lastValidatedAt?: string;
+    userConnection?: ConnectionStatusResponse;
+    createdAt: string;
+    updatedAt: string;
+    archivedAt?: string;
+}
+interface IntegrationOAuthConfigInput {
+    provider?: string;
+    issuer?: string;
+    scopes?: string[];
+}
+interface CreateIntegrationInput {
+    name: string;
+    url: string;
+    authMode?: IntegrationAuthMode;
+    oauth?: IntegrationOAuthConfigInput;
+    capabilities?: IntegrationCapabilities;
+    serverToken?: string;
+}
+interface UpdateIntegrationInput {
+    name?: string;
+    url?: string;
+    authMode?: IntegrationAuthMode;
+    oauth?: IntegrationOAuthConfigInput;
+    capabilities?: IntegrationCapabilities;
+    serverToken?: string;
+}
+interface CreateIntegrationResponse {
+    integration: Integration;
+}
+interface IntegrationResponse {
+    integration: Integration;
+}
+interface ListIntegrationsResponse {
+    items: Integration[];
+    nextCursor?: string;
+}
+interface ValidateIntegrationResponse {
+    status: IntegrationValidationStatus;
+    message?: string;
+}
+type ConnectionStatus = "connected" | "disconnected";
+interface ConnectionStatusResponse {
+    connected: boolean;
+    status?: ConnectionStatus;
+    expiresAt?: string;
+    displayName?: string;
+}
+interface ConnectionResponse {
+    connection: ConnectionStatusResponse;
+}
+interface AddUserTokenInput {
+    token: string;
+}
+interface ServiceAccount {
+    id: string;
+    name: string;
+    description: string | null;
+    createdAt: string;
+}
+interface ServiceAccountCredentials {
+    clientId: string;
+    clientSecret: string;
+}
+interface CreateServiceAccountInput {
+    name: string;
+    description?: string;
+}
+interface CreateServiceAccountResponse {
+    serviceAccount: ServiceAccount;
+    credentials: ServiceAccountCredentials;
+}
+interface RotateSecretResponse {
+    credentials: ServiceAccountCredentials;
+}
+interface ListServiceAccountsResponse {
+    items: ServiceAccount[];
+    nextCursor: string | null;
+}
+interface ServiceAccountResponse {
+    serviceAccount: ServiceAccount;
+}
+type AgentSessionStatus = "active" | "disconnected";
+type AgentSessionDerivedStatus = "active" | "idle" | "expired" | "disconnected";
+interface AgentSession {
+    id: string;
+    agentId: string;
+    organizationId: string;
+    name: string;
+    hostname?: string | null;
+    userAgent?: string | null;
+    clientInfo?: Record<string, unknown> | null;
+    status: AgentSessionStatus;
+    derivedStatus: AgentSessionDerivedStatus;
+    connectedAt?: string;
+    lastActiveAt?: string;
+    disconnectedAt?: string;
+    tokenExpiresAt?: string;
+    createdAt: string;
+}
+interface AgentSessionResponse {
+    session: AgentSession;
+}
+interface ListAgentSessionsResponse {
+    items: AgentSession[];
+}
+interface RevokeAllSessionsResponse {
+    success: boolean;
+    disconnectedCount: number;
+}
+interface Trace {
+    traceId: string | null;
+    sessionId: string;
+    startedAt: string | null;
+    endedAt: string | null;
+    eventCount: number;
+    okCount?: number;
+    warnCount?: number;
+    errorCount?: number;
+    agentId?: string;
+    ownerUserId?: string;
+    ownerEmail?: string;
+    agentName?: string;
+    agentSessionId?: string;
+    agentSessionName?: string;
+}
+interface TraceEvent {
+    id: string;
+    createdAt: string;
+    sessionId: string;
+    agentId: string;
+    traceId?: string | null;
+    apiKeyId?: string | null;
+    eventType: string;
+    status: string;
+    durationMs?: number | null;
+    integrationId?: string | null;
+    toolName?: string | null;
+    errorMessage?: string | null;
+    bytesIn?: number | null;
+    bytesOut?: number | null;
+    requestJson?: unknown;
+    responseJson?: unknown;
+    parentEventId?: string | null;
+    agentSessionId?: string | null;
+    /** @deprecated Use createdAt */
+    timestamp?: string;
+    /** @deprecated Use status */
+    level?: "ok" | "warn" | "error";
+    /** @deprecated Use eventType */
+    type?: string;
+    /** @deprecated May be encoded in requestJson/responseJson */
+    method?: string;
+    /** @deprecated Use toolName */
+    tool?: string;
+    /** @deprecated Use durationMs */
+    duration?: number;
+    /** @deprecated Use status/errorMessage fields */
+    errorType?: string;
+    /** @deprecated May be encoded in requestJson/responseJson */
+    metadata?: Record<string, unknown>;
+}
+interface ListTracesResponse {
+    items: Trace[];
+    nextCursor?: string;
+}
+interface TraceResponse {
+    trace: Trace;
+    events: TraceEvent[];
+}
+interface McpEvent {
+    id: string;
+    createdAt: string;
+    agentId: string;
+    integrationId: string | null;
+    toolName: string | null;
+    eventType: string;
+    status: string;
+}
+interface McpEventListResponse {
+    items: McpEvent[];
+}
+/**
+ * @deprecated Use McpEventListResponse instead.
+ */
+type ListEventsResponse = McpEventListResponse;
+interface TraceStats {
+    totalTraces: number;
+    totalEvents: number;
+    eventCounts: {
+        ok: number;
+        warn: number;
+        error: number;
+    };
+    errorRate: number;
+    latency: {
+        avg: number;
+        p50: number;
+        p95: number;
+        p99: number;
+    };
+    bytesTransferred: {
+        in: number;
+        out: number;
+    };
+    errorsByType: Array<{
+        type: string;
+        count: number;
+        percentage: number;
+    }>;
+    topTools: Array<{
+        name: string;
+        count: number;
+        avgDuration: number;
+    }>;
+    timeline: Array<{
+        date: string;
+        traceCount: number;
+        eventCount: number;
+        warnCount: number;
+        errorCount: number;
+        bytesIn: number;
+        bytesOut: number;
+    }>;
+}
+interface TraceStatsResponse {
+    stats: TraceStats;
+}
+interface PaginationParams {
+    cursor?: string;
+    limit?: number;
+}
+interface OAuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    tokenType: string;
+    scope?: string;
+    expiresAt?: string;
+}
+/**
+ * RFC 8693 Token Exchange grant type
+ */
+declare const TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange";
+/**
+ * RFC 8693 token type identifier for access tokens
+ */
+declare const TOKEN_TYPE_ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token";
+/**
+ * Request body for RFC 8693 token exchange
+ */
+interface TokenExchangeRequest {
+    grant_type: typeof TOKEN_EXCHANGE_GRANT_TYPE;
+    subject_token: string;
+    subject_token_type?: string;
+    resource: string;
+    scope?: string;
+    audience?: string;
+}
+/**
+ * Response from RFC 8693 token exchange
+ */
+interface TokenExchangeResponse {
+    access_token: string;
+    issued_token_type: string;
+    token_type: string;
+    expires_in?: number;
+    scope?: string;
+    refresh_token?: string;
+}
+interface KontextManagementClientConfig {
+    /**
+     * Base URL for the Kontext API (e.g., "https://api.kontext.dev")
+     */
+    baseUrl: string;
+    /**
+     * API version to use (default: "v1")
+     */
+    apiVersion?: string;
+    /**
+     * OAuth token endpoint URL (optional)
+     * If not specified, defaults to `${baseUrl}/oauth2/token`
+     * Useful for local development where Hydra runs on a different port
+     */
+    tokenUrl?: string;
+    /**
+     * OAuth scopes to request (optional)
+     * Defaults to ["management:all"]
+     */
+    scopes?: string[];
+    /**
+     * OAuth audience for token requests (optional)
+     * If not specified, defaults to `${baseUrl}/api/${apiVersion}`
+     * Required for Hydra token introspection
+     */
+    audience?: string;
+    /**
+     * Service account credentials for authentication
+     */
+    credentials: {
+        clientId: string;
+        clientSecret: string;
+    };
+}
+
+export { TOKEN_TYPE_ACCESS_TOKEN as $, type ApplicationResponse as A, type ConnectionResponse as B, type CreateServiceAccountInput as C, type ConnectionStatus as D, type ConnectionStatusResponse as E, type CreateApplicationOAuthInput as F, type Integration as G, type IntegrationAuthMode as H, type IntegrationResponse as I, type IntegrationCapabilities as J, type KontextManagementClientConfig as K, type ListServiceAccountsResponse as L, type McpEventListResponse as M, type IntegrationOAuthConfigInput as N, type IntegrationOAuthSummary as O, type PaginationParams as P, type IntegrationValidationStatus as Q, type RotateSecretResponse as R, type ServiceAccountResponse as S, type TokenExchangeRequest as T, type UpdateApplicationInput as U, type ValidateIntegrationResponse as V, type ListEventsResponse as W, type McpEvent as X, type OAuthTokens as Y, type ServiceAccount as Z, TOKEN_EXCHANGE_GRANT_TYPE as _, type TokenExchangeResponse as a, type Trace as a0, type TraceEvent as a1, type TraceStats as a2, type CreateServiceAccountResponse as b, type CreateApplicationInput as c, type CreateApplicationResponse as d, type ListApplicationsResponse as e, type ApplicationOAuthResponse as f, type UpdateApplicationOAuthInput as g, type RotateApplicationSecretResponse as h, type ApplicationIntegrationsResponse as i, type UpdateApplicationIntegrationsInput as j, type RevokeAllSessionsResponse as k, type CreateIntegrationInput as l, type CreateIntegrationResponse as m, type ListIntegrationsResponse as n, type UpdateIntegrationInput as o, type ListAgentSessionsResponse as p, type AgentSessionResponse as q, type ListTracesResponse as r, type TraceResponse as s, type TraceStatsResponse as t, type AddUserTokenInput as u, type AgentSession as v, type AgentSessionDerivedStatus as w, type AgentSessionStatus as x, type Application as y, type ApplicationOAuth as z };

package/dist/types-RIzHnRpk.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Storage interface for persisting SDK state
+ */
+/**
+ * Generic storage interface for the Kontext SDK
+ * Implementations can store data in memory, file system, or external services
+ */
+interface KontextStorage {
+    /**
+     * Retrieve a JSON value by key
+     * @param key Storage key
+     * @returns The stored value or undefined if not found
+     */
+    getJson<T>(key: string): Promise<T | undefined>;
+    /**
+     * Store a JSON value by key
+     * @param key Storage key
+     * @param value The value to store, or undefined to delete
+     */
+    setJson<T>(key: string, value: T | undefined): Promise<void>;
+}
+
+export type { KontextStorage as K };

package/dist/types-RIzHnRpk.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Storage interface for persisting SDK state
+ */
+/**
+ * Generic storage interface for the Kontext SDK
+ * Implementations can store data in memory, file system, or external services
+ */
+interface KontextStorage {
+    /**
+     * Retrieve a JSON value by key
+     * @param key Storage key
+     * @returns The stored value or undefined if not found
+     */
+    getJson<T>(key: string): Promise<T | undefined>;
+    /**
+     * Store a JSON value by key
+     * @param key Storage key
+     * @param value The value to store, or undefined to delete
+     */
+    setJson<T>(key: string, value: T | undefined): Promise<void>;
+}
+
+export type { KontextStorage as K };

package/dist/verifier-CoJmYiw3.d.cts

@@ -0,0 +1,109 @@
+/**
+ * Token verification error codes.
+ * These provide structured error information for debugging and error handling.
+ */
+type TokenVerificationErrorCode = "INVALID_TOKEN_FORMAT" | "INVALID_SIGNATURE" | "TOKEN_EXPIRED" | "TOKEN_NOT_YET_VALID" | "INVALID_ISSUER" | "INVALID_AUDIENCE" | "MISSING_SCOPE" | "MISSING_CLAIMS" | "JWKS_FETCH_FAILED" | "UNKNOWN_KID" | "UNSUPPORTED_ALGORITHM";
+/**
+ * Error thrown when token verification fails.
+ * Contains a structured error code for programmatic handling.
+ */
+declare class TokenVerificationError extends Error {
+    readonly code: TokenVerificationErrorCode;
+    constructor(code: TokenVerificationErrorCode, message: string);
+}
+
+/**
+ * Configuration for KontextTokenVerifier.
+ */
+interface KontextTokenVerifierConfig {
+    /** JWKS endpoint URL (e.g., "https://api.kontext.dev/.well-known/jwks.json") */
+    jwksUrl: string;
+    /** Expected issuer claim (iss) — may be a single string or an array of accepted issuers */
+    issuer: string | string[];
+    /** Expected audience claim(s) - token must contain at least one */
+    audience: string | string[];
+    /** Required scopes - token must contain all of these */
+    requiredScopes?: string[];
+    /** JWKS cache TTL in milliseconds (default: 5 minutes) */
+    cacheTtlMs?: number;
+    /** Minimum time between JWKS refetches in milliseconds (default: 30 seconds) */
+    refetchCooldownMs?: number;
+    /** Clock tolerance in seconds for expiration/not-before checks (default: 30) */
+    clockToleranceSec?: number;
+    /** Custom fetch function for testing */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * JWT payload structure from verified token.
+ */
+interface JwtPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    jti?: string;
+    client_id?: string;
+    scope?: string;
+    [key: string]: unknown;
+}
+/**
+ * Verified token claims returned on successful verification.
+ */
+interface VerifiedTokenClaims {
+    /** Subject claim (sub) */
+    sub: string;
+    /** Client ID (client_id claim or sub) */
+    clientId: string;
+    /** Scopes (space-separated scope claim split into array) */
+    scopes: string[];
+    /** Expiration time as Date */
+    expiresAt: Date;
+    /** JWT ID (jti) if present */
+    jti?: string;
+    /** Raw payload for access to additional claims */
+    payload: JwtPayload;
+}
+/**
+ * Result type for token verification.
+ * Provides structured success/failure information.
+ */
+type VerifyResult = {
+    success: true;
+    claims: VerifiedTokenClaims;
+} | {
+    success: false;
+    error: TokenVerificationError;
+};
+
+declare class KontextTokenVerifier {
+    private readonly config;
+    private readonly jwksClient;
+    private readonly audiences;
+    constructor(config: KontextTokenVerifierConfig);
+    /**
+     * Verify a JWT token.
+     *
+     * @param token - The JWT token string (without "Bearer " prefix)
+     * @returns VerifyResult with success=true and claims, or success=false and error
+     */
+    verify(token: string): Promise<VerifyResult>;
+    /**
+     * Verify a JWT token and return claims or null.
+     * Simpler API for cases where you don't need error details.
+     *
+     * @param token - The JWT token string (without "Bearer " prefix)
+     * @returns VerifiedTokenClaims if valid, null if invalid
+     */
+    verifyOrNull(token: string): Promise<VerifiedTokenClaims | null>;
+    /**
+     * Clear the JWKS cache, forcing a fresh fetch on next verification.
+     */
+    clearCache(): void;
+    private verifyInternal;
+    private parseScopes;
+    private extractKid;
+}
+
+export { type JwtPayload as J, KontextTokenVerifier as K, TokenVerificationError as T, type VerifiedTokenClaims as V, type KontextTokenVerifierConfig as a, type TokenVerificationErrorCode as b, type VerifyResult as c };

package/dist/verifier-CoJmYiw3.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Token verification error codes.
+ * These provide structured error information for debugging and error handling.
+ */
+type TokenVerificationErrorCode = "INVALID_TOKEN_FORMAT" | "INVALID_SIGNATURE" | "TOKEN_EXPIRED" | "TOKEN_NOT_YET_VALID" | "INVALID_ISSUER" | "INVALID_AUDIENCE" | "MISSING_SCOPE" | "MISSING_CLAIMS" | "JWKS_FETCH_FAILED" | "UNKNOWN_KID" | "UNSUPPORTED_ALGORITHM";
+/**
+ * Error thrown when token verification fails.
+ * Contains a structured error code for programmatic handling.
+ */
+declare class TokenVerificationError extends Error {
+    readonly code: TokenVerificationErrorCode;
+    constructor(code: TokenVerificationErrorCode, message: string);
+}
+
+/**
+ * Configuration for KontextTokenVerifier.
+ */
+interface KontextTokenVerifierConfig {
+    /** JWKS endpoint URL (e.g., "https://api.kontext.dev/.well-known/jwks.json") */
+    jwksUrl: string;
+    /** Expected issuer claim (iss) — may be a single string or an array of accepted issuers */
+    issuer: string | string[];
+    /** Expected audience claim(s) - token must contain at least one */
+    audience: string | string[];
+    /** Required scopes - token must contain all of these */
+    requiredScopes?: string[];
+    /** JWKS cache TTL in milliseconds (default: 5 minutes) */
+    cacheTtlMs?: number;
+    /** Minimum time between JWKS refetches in milliseconds (default: 30 seconds) */
+    refetchCooldownMs?: number;
+    /** Clock tolerance in seconds for expiration/not-before checks (default: 30) */
+    clockToleranceSec?: number;
+    /** Custom fetch function for testing */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * JWT payload structure from verified token.
+ */
+interface JwtPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    nbf?: number;
+    jti?: string;
+    client_id?: string;
+    scope?: string;
+    [key: string]: unknown;
+}
+/**
+ * Verified token claims returned on successful verification.
+ */
+interface VerifiedTokenClaims {
+    /** Subject claim (sub) */
+    sub: string;
+    /** Client ID (client_id claim or sub) */
+    clientId: string;
+    /** Scopes (space-separated scope claim split into array) */
+    scopes: string[];
+    /** Expiration time as Date */
+    expiresAt: Date;
+    /** JWT ID (jti) if present */
+    jti?: string;
+    /** Raw payload for access to additional claims */
+    payload: JwtPayload;
+}
+/**
+ * Result type for token verification.
+ * Provides structured success/failure information.
+ */
+type VerifyResult = {
+    success: true;
+    claims: VerifiedTokenClaims;
+} | {
+    success: false;
+    error: TokenVerificationError;
+};
+
+declare class KontextTokenVerifier {
+    private readonly config;
+    private readonly jwksClient;
+    private readonly audiences;
+    constructor(config: KontextTokenVerifierConfig);
+    /**
+     * Verify a JWT token.
+     *
+     * @param token - The JWT token string (without "Bearer " prefix)
+     * @returns VerifyResult with success=true and claims, or success=false and error
+     */
+    verify(token: string): Promise<VerifyResult>;
+    /**
+     * Verify a JWT token and return claims or null.
+     * Simpler API for cases where you don't need error details.
+     *
+     * @param token - The JWT token string (without "Bearer " prefix)
+     * @returns VerifiedTokenClaims if valid, null if invalid
+     */
+    verifyOrNull(token: string): Promise<VerifiedTokenClaims | null>;
+    /**
+     * Clear the JWKS cache, forcing a fresh fetch on next verification.
+     */
+    clearCache(): void;
+    private verifyInternal;
+    private parseScopes;
+    private extractKid;
+}
+
+export { type JwtPayload as J, KontextTokenVerifier as K, TokenVerificationError as T, type VerifiedTokenClaims as V, type KontextTokenVerifierConfig as a, type TokenVerificationErrorCode as b, type VerifyResult as c };