@gdrl/kronos-lib 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,336 @@
+import { K as KronosClientConfig, I as IngestResponse, a as IngestStatusResponse, C as CreateMCPServerResponse, L as ListMCPServersResponse, G as GetMCPServerResponse, b as ConnectMCPServerResponse, R as RotateMCPServerTokenResponse, M as MemoryStatsResponse, S as ScratchsheetResponse, c as ListScopesResponse, d as GetScopeResponse, e as ScopeSpec, f as CreateScopeResponse, U as UpdateScopeResponse, g as ListTriggersResponse, h as CreateTriggerRequest, i as CreateTriggerResponse, T as TriggerRecord, j as UpdateTriggerRequest, k as UpdateTriggerResponse, D as DeleteTriggerResponse, l as CreateFrontendTokenResponse, m as SkillManageParams, n as SkillManageResponse, o as ContextGraphSummaryResponse, p as ContextGraphReadResponse } from './types-Gt5ZdRxW.js';
+export { x as ConnectMCPServerRequest, Y as ContextGraphProcedureSummary, F as CreateFrontendTokenRequest, t as CreateMCPServerRequest, B as CreateScopeRequest, r as IngestMemoryDisposition, s as IngestRequest, q as IngestStatus, w as MCPServerDetails, u as MCPServerStatus, v as MCPServerToolCapabilities, O as OnTriggered, y as RotateMCPServerTokenRequest, A as ScopeDetail, z as ScopeSummary, N as SkillFileContentMode, P as SkillFileInput, Q as SkillFileRecord, H as SkillFileType, W as SkillMetadataRecord, J as SkillReadMode, X as SkillSummaryRecord, V as SkillTreeNode, E as TriggerType } from './types-Gt5ZdRxW.js';
+
+declare class KronosClient {
+    private readonly workerUrl;
+    private readonly mastraUrl;
+    private readonly apiKey;
+    private readonly appId;
+    constructor(config: KronosClientConfig);
+    /**
+     * Perform a health check to verify the client can connect to the Kronos worker
+     * This is called automatically during initialization
+     */
+    private healthCheck;
+    private workerFetch;
+    private mastraFetch;
+    private handleResponse;
+    /**
+     * Submit a document for ingestion.
+     * @param params - source_type, content, optional metadata, addToMemory, and idempotencyKey
+     * @returns ingest_id
+     */
+    ingest(params: {
+        tenant_user_id: string;
+        source_type: string;
+        priority?: 'low' | 'medium' | 'high';
+        addToMemory?: boolean;
+        content: {
+            type: 'text';
+            text: string;
+        };
+        metadata?: Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<IngestResponse>;
+    /**
+     * Get the status of an ingest.
+     */
+    getIngestStatus(ingestId: string): Promise<IngestStatusResponse>;
+    /**
+     * Create an MCP server scoped to the given scopes.
+     * Use connectMCPServer() to get a short-lived access token for MCP auth.
+     */
+    createMCPServer(params: {
+        tenant_user_id: string;
+        name: string;
+        /** Omit or pass [] for all-memory access. */
+        scope_ids?: string[] | null;
+        description?: string;
+        options?: {
+            /** Expose `search_skills` and `read_skill`. Defaults to true. */
+            exposeSkillsTool?: boolean;
+            /** Expose the read-only `context_graph` tool. Defaults to false. */
+            exposeContextGraphTool?: boolean;
+        };
+    }): Promise<CreateMCPServerResponse>;
+    /**
+     * List MCP servers for a user. Returns metadata only (no token).
+     */
+    listMCPServers(params: {
+        tenant_user_id: string;
+    }): Promise<ListMCPServersResponse>;
+    /**
+     * Get MCP server details for a user by server ID. Returns metadata only (no token).
+     */
+    getMCPServer(params: {
+        tenant_user_id: string;
+        serverId: string;
+    }): Promise<GetMCPServerResponse>;
+    updateMCPServer(params: {
+        tenant_user_id: string;
+        serverId: string;
+        tool_capabilities: {
+            skills: boolean;
+            context_graph: boolean;
+        };
+    }): Promise<GetMCPServerResponse>;
+    /**
+     * Connect to an MCP server by ID and receive a short-lived access token.
+     * Use the returned access_token as Bearer token when calling the MCP endpoint.
+     */
+    connectMCPServer(params: {
+        tenant_user_id: string;
+        serverId: string;
+    }): Promise<ConnectMCPServerResponse>;
+    /**
+     * Rotate the token for an MCP server. The new token is returned only on rotate.
+     */
+    rotateMCPServerToken(params: {
+        tenant_user_id: string;
+        serverId: string;
+    }): Promise<RotateMCPServerTokenResponse>;
+    /**
+     * Get memory stats for a user (total claim count across entire memory graph).
+     * Worker caches the response for 5 minutes per user.
+     */
+    getMemoryStats(params: {
+        tenant_user_id: string;
+    }): Promise<MemoryStatsResponse>;
+    /**
+     * Read the current scratchsheet document for a user.
+     */
+    getScratchsheet(params: {
+        tenant_user_id: string;
+    }): Promise<ScratchsheetResponse>;
+    /**
+     * List scopes for a user. Returns full scope details. Cached 5 min per user.
+     */
+    listScopes(params: {
+        tenant_user_id: string;
+    }): Promise<ListScopesResponse>;
+    /**
+     * Get a single scope by ID. Returns full scope details.
+     */
+    getScope(params: {
+        tenant_user_id: string;
+        scope_id: string;
+    }): Promise<GetScopeResponse>;
+    /**
+     * Create a scope. A backfill job runs asynchronously to populate it.
+     * If spec.allowed_source_types is omitted, it defaults to ['all'].
+     * Uses the Worker so the scopes list cache is invalidated after create.
+     */
+    createScope(params: {
+        tenant_user_id: string;
+        spec: ScopeSpec;
+        created_by: string;
+        description?: string;
+    }): Promise<CreateScopeResponse>;
+    /**
+     * Update a scope. Only provided fields are updated.
+     * If include_query, exclude_query, match_mode, time_range, or allowed_source_types change,
+     * a backfill job runs to recompute membership (response includes backfill_job_id).
+     * Otherwise only DB and Neo4j metadata are updated.
+     */
+    updateScope(params: {
+        tenant_user_id: string;
+        scope_id: string;
+        name?: string;
+        description?: string | null;
+        include_query?: string;
+        exclude_query?: string | null;
+        match_mode?: 'strict' | 'broad';
+        time_range?: {
+            start?: string;
+            end?: string;
+        };
+        allowed_source_types?: string[] | 'all';
+    }): Promise<UpdateScopeResponse>;
+    /**
+     * Soft-delete a scope. Invalidates the scopes list cache for that user.
+     */
+    deleteScope(params: {
+        tenant_user_id: string;
+        scope_id: string;
+    }): Promise<{
+        deleted: boolean;
+    }>;
+    /**
+     * Verify a webhook secret for a trigger.
+     * This method calls the Kronos worker API to verify the webhook secret.
+     *
+     * @param params - app_id, tenant_user_id, trigger_id and received_secret to verify
+     * @returns true if secret is valid, false otherwise
+     */
+    verifyWebhookSecret(params: {
+        tenant_user_id: string;
+        trigger_id: string;
+        received_secret: string;
+    }): Promise<boolean>;
+    /**
+     * List triggers for a tenant user.
+     */
+    listTriggers(params: {
+        tenant_user_id: string;
+    }): Promise<ListTriggersResponse>;
+    /**
+     * Create a trigger.
+     * Supports NL creation (trigger_description) or manual creation (trigger_type/trigger_spec).
+     *
+     * @returns CreateTriggerResponse (accepted for NL, trigger_id for manual)
+     */
+    createTrigger(params: {
+        tenant_user_id: string;
+        webhook_url: string;
+        webhook_secret: string;
+        title?: string | null;
+        action_description?: string;
+        skill_id?: string;
+        skill_version_id?: string;
+        trigger_description?: string;
+        trigger_type?: CreateTriggerRequest['trigger_type'];
+        trigger_spec?: CreateTriggerRequest['trigger_spec'];
+        next_run_at?: string;
+        on_triggered?: CreateTriggerRequest['on_triggered'];
+        metadata?: Record<string, unknown>;
+        idempotencyKey?: string;
+    }): Promise<CreateTriggerResponse>;
+    /**
+     * Get details for a specific trigger.
+     * Uses listTriggers and filters by trigger_id.
+     */
+    getTriggerDetails(params: {
+        tenant_user_id: string;
+        trigger_id: string;
+    }): Promise<TriggerRecord>;
+    /**
+     * Update a trigger.
+     * Updates the webhook_url, action_description, status, or metadata of an existing trigger.
+     *
+     * @param params - app_id, tenant_user_id, trigger_id and fields to update
+     * @returns UpdateTriggerResponse with success status
+     */
+    updateTrigger(params: {
+        tenant_user_id: string;
+        trigger_id: string;
+        webhook_url?: string;
+        title?: string | null;
+        trigger_type?: UpdateTriggerRequest['trigger_type'];
+        trigger_spec?: UpdateTriggerRequest['trigger_spec'];
+        next_run_at?: UpdateTriggerRequest['next_run_at'];
+        action_description?: string;
+        skill_id?: string | null;
+        skill_version_id?: string | null;
+        on_triggered?: UpdateTriggerRequest['on_triggered'];
+        status?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<UpdateTriggerResponse>;
+    /**
+     * Delete a trigger.
+     */
+    deleteTrigger(params: {
+        tenant_user_id: string;
+        trigger_id: string;
+    }): Promise<DeleteTriggerResponse>;
+    /**
+     * Issue a short-lived, user-scoped frontend token.
+     * The browser can use this token directly against the Kronos worker for
+     * allowed operations (e.g. trigger CRUD) without needing the app API key.
+     *
+     * This method must be called from a trusted server environment.
+     */
+    createFrontendToken(params: {
+        tenantUserId: string;
+        ttlSeconds?: number;
+        ops?: string[];
+    }): Promise<CreateFrontendTokenResponse>;
+    /**
+     * Canonical skills API with operation-based contract.
+     */
+    manageSkill(params: SkillManageParams): Promise<SkillManageResponse>;
+    private resolveContextGraphSkillId;
+    private parseContextGraphProcedures;
+    getContextGraph(params: {
+        tenant_user_id: string;
+    }): Promise<ContextGraphSummaryResponse>;
+    readContextGraph(params: {
+        tenant_user_id: string;
+        path?: string;
+    }): Promise<ContextGraphReadResponse>;
+}
+
+/**
+ * Generate an idempotency key for ingest requests.
+ * Uses crypto.randomUUID() when available; falls back to a timestamp-based value.
+ * Callers can pass their own key via the ingest options to achieve true idempotency.
+ */
+declare function generateIdempotencyKey(): string;
+
+/**
+ * Webhook verification utilities for Kronos triggers
+ * Provides secure constant-time comparison for webhook secrets
+ */
+/**
+ * Verify a webhook secret using constant-time comparison to prevent timing attacks.
+ *
+ * @param receivedSecret - The secret received in the webhook header
+ * @param storedSecret - The secret stored in the database for the trigger
+ * @returns true if secrets match, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSecret } from '@gdrl/kronos-lib/webhook-verification';
+ *
+ * const isValid = verifyWebhookSecret(
+ *   request.headers.get('X-Kronos-Webhook-Secret'),
+ *   trigger.webhook_secret
+ * );
+ *
+ * if (!isValid) {
+ *   return new Response('Unauthorized', { status: 401 });
+ * }
+ * ```
+ */
+declare function verifyWebhookSecret(receivedSecret: string | null | undefined, storedSecret: string | null | undefined): boolean;
+
+/**
+ * Base error for Kronos API failures
+ */
+declare class KronosError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined, body?: unknown | undefined);
+}
+/**
+ * 400 Bad Request - invalid or missing parameters
+ */
+declare class KronosBadRequestError extends KronosError {
+    constructor(message: string, body?: unknown);
+}
+/**
+ * 401 Unauthorized - invalid or missing API key
+ */
+declare class KronosUnauthorizedError extends KronosError {
+    constructor(message: string, body?: unknown);
+}
+/**
+ * 403 Forbidden - valid auth but insufficient permissions
+ */
+declare class KronosForbiddenError extends KronosError {
+    constructor(message: string, body?: unknown);
+}
+/**
+ * 404 Not Found - resource does not exist
+ */
+declare class KronosNotFoundError extends KronosError {
+    constructor(message: string, body?: unknown);
+}
+/**
+ * 5xx or network/unknown errors
+ */
+declare class KronosServerError extends KronosError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+
+export { ConnectMCPServerResponse, ContextGraphReadResponse, ContextGraphSummaryResponse, CreateFrontendTokenResponse, CreateMCPServerResponse, CreateScopeResponse, CreateTriggerRequest, CreateTriggerResponse, DeleteTriggerResponse, GetMCPServerResponse, GetScopeResponse, IngestResponse, IngestStatusResponse, KronosBadRequestError, KronosClient, KronosClientConfig, KronosError, KronosForbiddenError, KronosNotFoundError, KronosServerError, KronosUnauthorizedError, ListMCPServersResponse, ListScopesResponse, ListTriggersResponse, MemoryStatsResponse, RotateMCPServerTokenResponse, ScopeSpec, ScratchsheetResponse, SkillManageParams, SkillManageResponse, TriggerRecord, UpdateTriggerRequest, UpdateTriggerResponse, generateIdempotencyKey, verifyWebhookSecret };