@gdrl/kronos-lib 0.1.0

package/README.md

@@ -0,0 +1,208 @@
+# kronos-lib
+
+Lightweight TypeScript SDK for the [Kronos Knowledge Graph](https://github.com/your-org/kronos) API. Use it from Next.js, Node.js, or any JavaScript environment with `fetch` (Node 18+, browsers).
+
+## Installation
+
+```bash
+npm install kronos-lib
+# or
+pnpm add kronos-lib
+# or
+yarn add kronos-lib
+```
+
+## Quick Start
+
+```typescript
+import { KronosClient } from '@gdrl/kronos-lib';
+
+const client = new KronosClient({
+  workerUrl: 'https://your-worker.workers.dev',
+  mastraUrl: 'https://your-mastra-server.com',
+  apiKey: 'your-app-api-key',
+  appId: 'your-app-id',
+  tenantUserId: 'user-123',
+});
+
+// Ingest a document
+const { ingest_id } = await client.ingest({
+  source_type: 'email',
+  content: { type: 'text', text: 'Document content...' },
+  metadata: { sender: 'user@example.com' },
+});
+
+// Check ingest status
+const status = await client.getIngestStatus(ingest_id);
+
+// Create an MCP server
+const mcp = await client.createMCPServer({
+  name: 'My MCP Server',
+  collection_ids: ['col-1', 'col-2'],
+  description: 'Optional description',
+});
+
+// Connect to the MCP server (short-lived access token, ~1 day)
+const connection = await client.connectMCPServer({
+  serverId: mcp.mcp_server_id,
+});
+// connection.url is the full MCP endpoint; connection.access_token is the Bearer token.
+
+// Query the knowledge graph
+const results = await client.query({
+  query: 'What happened in Tokyo?',
+  collection_ids: ['col-1', 'col-2'],
+});
+// results.episodes, results.entities, results.attributes, results.direct_answer
+
+// Create a collection
+const collection = await client.createCollection({
+  spec: {
+    name: 'Work Emails',
+    include_query: 'work OR project',
+    scope: 'episode',
+    match_mode: 'broad',
+  },
+  created_by: 'user-123',
+});
+// collection.collection_id, collection.backfill_job_id
+
+// Refresh collections for new episodes
+await client.refreshCollections({ episode_ids: ['ep-1', 'ep-2'] });
+```
+
+## Configuration
+
+| Option        | Description                                                                 |
+|---------------|-----------------------------------------------------------------------------|
+| `workerUrl`   | Base URL of the Cloudflare Worker (ingest, MCP server create/rotate).      |
+| `mastraUrl`   | Base URL of the Mastra server (query, collections).                         |
+| `apiKey`      | App API key; used as `Authorization: Bearer` for Worker endpoints.         |
+| `appId`       | App ID; injected into Worker and Mastra request bodies.                     |
+| `tenantUserId`| Tenant/user ID; injected into request bodies.                               |
+
+## API Overview
+
+### Ingest (Worker)
+
+- **`ingest(params)`** – Submit a document. Requires `source_type` and `content: { type: 'text', text }`. Optional: `metadata`, `addToMemory`, `idempotencyKey`. `addToMemory` defaults to `true`; set it to `false` to run ingest-trigger workflows without chunking or adding the content to memory. If `idempotencyKey` is omitted, one is generated. Returns `{ ingest_id }`.
+- **`getIngestStatus(ingestId)`** – Get status and progress of an ingest.
+
+### MCP Servers (Worker)
+
+- **`createMCPServer(params)`** – Create an MCP server. Requires `name`, `collection_ids`. Optional: `description`. Returns MCP server metadata including `mcp_server_id`.
+- **`listMCPServers(params)`** – List MCP servers for a user. Returns metadata only (no token).
+- **`getMCPServer(params)`** – Get MCP server metadata by `serverId` (no token).
+- **`connectMCPServer(params)`** – Issue a short-lived MCP access token for a server. Returns `{ mcp_server_id, url, access_token, expires_at }`.
+- **`rotateMCPServerToken(serverId)`** – Legacy token rotation endpoint (generally not needed with short-lived connect tokens).
+
+### Query (Mastra)
+
+- **`query(params)`** – Query the graph. Requires `query`, `collection_ids`. Returns `{ episodes, entities, attributes, direct_answer? }`.
+
+### Collections (Mastra)
+
+- **`createCollection(params)`** – Create a collection. Requires `spec` (e.g. `name`, `include_query`, `scope`, `match_mode`), `created_by`. Optional: `description`. Returns `{ collection_id, backfill_job_id }`.
+- **`refreshCollections(params)`** – Refresh collection membership for `episode_ids`. Optional: `mode` (default `'new_episodes_only'`). Returns `{ accepted: true }`.
+
+## Idempotency
+
+For `ingest`, the Worker requires an `Idempotency-Key` header. You can pass `idempotencyKey` in the options; if omitted, the SDK generates one. For true idempotency (e.g. retries), pass a stable key (e.g. hash of `source_type` + `content.text` or your own id).
+
+## Error Handling
+
+The SDK throws typed errors for HTTP failures:
+
+- `KronosBadRequestError` (400)
+- `KronosUnauthorizedError` (401)
+- `KronosForbiddenError` (403)
+- `KronosNotFoundError` (404)
+- `KronosServerError` (5xx)
+- `KronosError` (other)
+
+All extend `KronosError` and include `status`, `code`, and `body` when available.
+
+```typescript
+import { KronosClient, KronosNotFoundError } from '@gdrl/kronos-lib';
+
+try {
+  await client.getIngestStatus('missing-id');
+} catch (e) {
+  if (e instanceof KronosNotFoundError) {
+    console.log('Ingest not found:', e.body);
+  }
+  throw e;
+}
+```
+
+## React integration (optional)
+
+If you're building a React or Next.js app, you can use the optional React hook
+exported from the `kronos-lib/react` subpath.
+
+### `useKronos` (triggers)
+
+For now, `useKronos` focuses on trigger operations (more domains can be added over time):
+
+```tsx
+import { useKronos, type KronosTriggerOps } from '@gdrl/kronos-lib/react';
+
+const ops: KronosTriggerOps = {
+  async listTriggers() {
+    // Example: call your own app route that proxies to Kronos
+    const response = await fetch('/api/mercury/triggers');
+    const body = await response.json();
+    return {
+      triggers: body.triggers ?? [],
+      count: body.count ?? (body.triggers ?? []).length,
+    };
+  },
+  async createNlTrigger({ nl, actionDescription }) {
+    const response = await fetch('/api/mercury/triggers', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ type: 'nl_webhook', nl, actionDescription }),
+    });
+    const body = await response.json();
+    return { triggerId: body.trigger_id ?? null };
+  },
+};
+
+function Automations() {
+  const {
+    triggers,
+    triggersLoading,
+    triggersError,
+    refreshTriggers,
+    createNlTrigger,
+    createLoading,
+    createError,
+  } = useKronos({ ops, tenantUserId: 'current-user' });
+
+  // ...render UI...
+}
+```
+
+This pattern lets you keep API keys and webhook secrets on the server (behind your own API routes),
+while still getting a clean React hook surface for reading and creating triggers.
+
+## Types
+
+All request/response types are exported:
+
+- `IngestRequest`, `IngestResponse`, `IngestStatusResponse`
+- `CreateMCPServerRequest`, `CreateMCPServerResponse`, `MCPServerDetails`, `ListMCPServersResponse`, `GetMCPServerResponse`, `ConnectMCPServerRequest`, `ConnectMCPServerResponse`
+- `RotateMCPServerTokenRequest`, `RotateMCPServerTokenResponse`
+- `QueryRequest`, `QueryResponse`, `EpisodeResult`, `EntityResult`, `AttributeResult`
+- `CollectionSpec`, `CreateCollectionRequest`, `CreateCollectionResponse`
+- `RefreshCollectionsRequest`, `RefreshCollectionsResponse`
+- `KronosClientConfig`
+
+## Requirements
+
+- Node.js 18+ or a modern browser (uses global `fetch`)
+- TypeScript 4.7+ recommended for types
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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.mjs';
+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.mjs';
+
+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 };