@gdrl/kronos-lib 0.1.0

package/dist/index.mjs

@@ -0,0 +1,713 @@
+// src/errors.ts
+var KronosError = class _KronosError extends Error {
+  constructor(message, status, code, body) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.name = "KronosError";
+    Object.setPrototypeOf(this, _KronosError.prototype);
+  }
+};
+var KronosBadRequestError = class _KronosBadRequestError extends KronosError {
+  constructor(message, body) {
+    super(message, 400, "bad_request", body);
+    this.name = "KronosBadRequestError";
+    Object.setPrototypeOf(this, _KronosBadRequestError.prototype);
+  }
+};
+var KronosUnauthorizedError = class _KronosUnauthorizedError extends KronosError {
+  constructor(message, body) {
+    super(message, 401, "unauthorized", body);
+    this.name = "KronosUnauthorizedError";
+    Object.setPrototypeOf(this, _KronosUnauthorizedError.prototype);
+  }
+};
+var KronosForbiddenError = class _KronosForbiddenError extends KronosError {
+  constructor(message, body) {
+    super(message, 403, "forbidden", body);
+    this.name = "KronosForbiddenError";
+    Object.setPrototypeOf(this, _KronosForbiddenError.prototype);
+  }
+};
+var KronosNotFoundError = class _KronosNotFoundError extends KronosError {
+  constructor(message, body) {
+    super(message, 404, "not_found", body);
+    this.name = "KronosNotFoundError";
+    Object.setPrototypeOf(this, _KronosNotFoundError.prototype);
+  }
+};
+var KronosServerError = class _KronosServerError extends KronosError {
+  constructor(message, status, body) {
+    super(message, status, "server_error", body);
+    this.name = "KronosServerError";
+    Object.setPrototypeOf(this, _KronosServerError.prototype);
+  }
+};
+
+// src/utils.ts
+function generateIdempotencyKey() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `idem_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+}
+
+// src/client.ts
+var WORKER_URL = "https://api.kronos.ai";
+var MASTRA_URL = "https://mastra.kronos.ai";
+var INTERNAL_CONTEXT_GRAPH_SKILL_NAME = "__internal_context_graph__";
+var KronosClient = class {
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new Error("KronosClient: apiKey is required in constructor");
+    }
+    if (!config.appId) {
+      throw new Error("KronosClient: appId is required in constructor");
+    }
+    this.workerUrl = WORKER_URL.replace(/\/$/, "");
+    this.mastraUrl = MASTRA_URL.replace(/\/$/, "");
+    this.apiKey = config.apiKey;
+    this.appId = config.appId;
+    console.log("[KronosClient] \u2705 KronosClient initialized:", {
+      appId: this.appId,
+      workerUrl: this.workerUrl,
+      mastraUrl: this.mastraUrl,
+      hasApiKey: !!this.apiKey
+    });
+    this.healthCheck().catch(() => {
+    });
+  }
+  /**
+   * Perform a health check to verify the client can connect to the Kronos worker
+   * This is called automatically during initialization
+   */
+  async healthCheck() {
+    try {
+      const response = await fetch(`${this.workerUrl}/health`, {
+        method: "GET",
+        headers: {
+          "Content-Type": "application/json"
+        }
+      });
+      if (response.ok) {
+        const data = await response.json();
+        if (data.status === "ok") {
+          console.log("[KronosClient] \u2705 Health check passed - Client is connected and working");
+        } else {
+          console.warn("[KronosClient] \u26A0\uFE0F  Health check returned unexpected status:", data);
+        }
+      } else {
+        console.warn(`[KronosClient] \u26A0\uFE0F  Health check failed with status ${response.status}. Client may not be working correctly.`);
+      }
+    } catch (error) {
+      console.warn("[KronosClient] \u26A0\uFE0F  Health check failed - Unable to connect to Kronos worker:", error.message);
+      console.warn("[KronosClient] Please verify that:");
+      console.warn("[KronosClient]   1. The worker URL is correct:", this.workerUrl);
+      console.warn("[KronosClient]   2. The worker is running and accessible");
+      console.warn("[KronosClient]   3. Network connectivity is available");
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Worker request helper (uses Bearer auth)
+  // ---------------------------------------------------------------------------
+  async workerFetch(path, options = {}) {
+    const { json, idempotencyKey, method } = options;
+    const headers = {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${this.apiKey}`
+    };
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+    const res = await fetch(`${this.workerUrl}${path}`, {
+      method: method ?? (json ? "POST" : "GET"),
+      headers,
+      body: json ? JSON.stringify(json) : void 0
+    });
+    return this.handleResponse(res);
+  }
+  // ---------------------------------------------------------------------------
+  // Mastra request helper (no Bearer auth per current API)
+  // ---------------------------------------------------------------------------
+  async mastraFetch(path, options = {}) {
+    const { json, method } = options;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    const res = await fetch(`${this.mastraUrl}${path}`, {
+      method: method ?? (json ? "POST" : "GET"),
+      headers,
+      body: json ? JSON.stringify(json) : void 0
+    });
+    return this.handleResponse(res);
+  }
+  async handleResponse(res) {
+    const text = await res.text();
+    let body = null;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    if (!res.ok) {
+      const errBody = body;
+      const message = errBody && typeof errBody.error === "string" ? errBody.error : `Request failed with status ${res.status}`;
+      switch (res.status) {
+        case 400:
+          throw new KronosBadRequestError(message, body);
+        case 401:
+          throw new KronosUnauthorizedError(message, body);
+        case 403:
+          throw new KronosForbiddenError(message, body);
+        case 404:
+          throw new KronosNotFoundError(message, body);
+        default:
+          if (res.status >= 500) {
+            throw new KronosServerError(message, res.status, body);
+          }
+          throw new KronosError(message, res.status, void 0, body);
+      }
+    }
+    return body ?? null;
+  }
+  // ---------------------------------------------------------------------------
+  // Ingest API
+  // ---------------------------------------------------------------------------
+  /**
+   * Submit a document for ingestion.
+   * @param params - source_type, content, optional metadata, addToMemory, and idempotencyKey
+   * @returns ingest_id
+   */
+  async ingest(params) {
+    const idempotencyKey = params.idempotencyKey ?? generateIdempotencyKey();
+    const body = {
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id,
+      source_type: params.source_type,
+      priority: params.priority,
+      addToMemory: params.addToMemory,
+      content: params.content,
+      metadata: params.metadata
+    };
+    return this.workerFetch("/v1/ingest", {
+      method: "POST",
+      json: body,
+      idempotencyKey
+    });
+  }
+  /**
+   * Get the status of an ingest.
+   */
+  async getIngestStatus(ingestId) {
+    return this.workerFetch(`/v1/ingest/${ingestId}`, {
+      method: "GET"
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // MCP Server API
+  // ---------------------------------------------------------------------------
+  /**
+   * Create an MCP server scoped to the given scopes.
+   * Use connectMCPServer() to get a short-lived access token for MCP auth.
+   */
+  async createMCPServer(params) {
+    const body = {
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id,
+      scope_ids: params.scope_ids ?? [],
+      name: params.name,
+      description: params.description,
+      options: {
+        exposeSkillsTool: params.options?.exposeSkillsTool ?? true,
+        exposeContextGraphTool: params.options?.exposeContextGraphTool ?? false
+      }
+    };
+    const res = await this.workerFetch("/v1/mcp-servers", { method: "POST", json: body });
+    return {
+      mcp_server_id: res.mcp_server_id,
+      url: res.url.startsWith("http") ? res.url : `${this.workerUrl}${res.url}`,
+      status: res.status,
+      name: res.name,
+      description: res.description,
+      scope_ids: res.scope_ids,
+      tool_capabilities: res.tool_capabilities ?? {
+        skills: true,
+        context_graph: false
+      }
+    };
+  }
+  /**
+   * List MCP servers for a user. Returns metadata only (no token).
+   */
+  async listMCPServers(params) {
+    const path = `/v1/mcp-servers?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, { method: "GET" });
+  }
+  /**
+   * Get MCP server details for a user by server ID. Returns metadata only (no token).
+   */
+  async getMCPServer(params) {
+    const path = `/v1/mcp-servers/${params.serverId}?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, { method: "GET" });
+  }
+  async updateMCPServer(params) {
+    const body = {
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id,
+      tool_capabilities: params.tool_capabilities
+    };
+    return this.workerFetch(`/v1/mcp-servers/${params.serverId}`, {
+      method: "PUT",
+      json: body
+    });
+  }
+  /**
+   * 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.
+   */
+  async connectMCPServer(params) {
+    const body = {
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    };
+    const res = await this.workerFetch(
+      `/v1/mcp-servers/${params.serverId}/connect`,
+      { method: "POST", json: body }
+    );
+    return {
+      ...res,
+      url: res.url.startsWith("http") ? res.url : `${this.workerUrl}${res.url}`
+    };
+  }
+  /**
+   * Rotate the token for an MCP server. The new token is returned only on rotate.
+   */
+  async rotateMCPServerToken(params) {
+    return this.workerFetch(
+      `/v1/mcp-servers/${params.serverId}/rotate-token`,
+      {
+        method: "POST",
+        json: { app_id: this.appId, tenant_user_id: params.tenant_user_id }
+      }
+    );
+  }
+  /**
+   * Get memory stats for a user (total claim count across entire memory graph).
+   * Worker caches the response for 5 minutes per user.
+   */
+  async getMemoryStats(params) {
+    const path = `/v1/memory-stats?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, { method: "GET" });
+  }
+  /**
+   * Read the current scratchsheet document for a user.
+   */
+  async getScratchsheet(params) {
+    const path = `/v1/scratchsheet?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, { method: "GET" });
+  }
+  /**
+   * List scopes for a user. Returns full scope details. Cached 5 min per user.
+   */
+  async listScopes(params) {
+    const path = `/v1/scopes?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, { method: "GET" });
+  }
+  /**
+   * Get a single scope by ID. Returns full scope details.
+   */
+  async getScope(params) {
+    const path = `/v1/scopes/${encodeURIComponent(params.scope_id)}?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, { method: "GET" });
+  }
+  // ---------------------------------------------------------------------------
+  // Scope API (Mastra)
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async createScope(params) {
+    const spec = {
+      ...params.spec,
+      allowed_source_types: params.spec.allowed_source_types ?? ["all"]
+    };
+    const body = {
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id,
+      spec,
+      created_by: params.created_by,
+      description: params.description
+    };
+    return this.workerFetch("/v1/scopes", {
+      method: "POST",
+      json: body
+    });
+  }
+  /**
+   * 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.
+   */
+  async updateScope(params) {
+    const { scope_id, tenant_user_id, ...patch } = params;
+    const body = {};
+    if (patch.name !== void 0) body.name = patch.name;
+    if (patch.description !== void 0) body.description = patch.description;
+    if (patch.include_query !== void 0) body.include_query = patch.include_query;
+    if (patch.exclude_query !== void 0) body.exclude_query = patch.exclude_query;
+    if (patch.match_mode !== void 0) body.match_mode = patch.match_mode;
+    if (patch.time_range !== void 0) body.time_range = patch.time_range;
+    if (patch.allowed_source_types !== void 0) body.allowed_source_types = patch.allowed_source_types;
+    const path = `/v1/scopes/${encodeURIComponent(scope_id)}?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, {
+      method: "PATCH",
+      json: body
+    });
+  }
+  /**
+   * Soft-delete a scope. Invalidates the scopes list cache for that user.
+   */
+  async deleteScope(params) {
+    const path = `/v1/scopes/${encodeURIComponent(params.scope_id)}?${new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    }).toString()}`;
+    return this.workerFetch(path, { method: "DELETE" });
+  }
+  // ---------------------------------------------------------------------------
+  // Webhook Verification API (Worker)
+  // ---------------------------------------------------------------------------
+  /**
+   * 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
+   */
+  async verifyWebhookSecret(params) {
+    const body = {
+      trigger_id: params.trigger_id,
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id,
+      received_secret: params.received_secret
+    };
+    try {
+      const response = await this.workerFetch("/v1/triggers/verify-webhook", {
+        method: "POST",
+        json: body
+      });
+      return response.valid;
+    } catch (error) {
+      console.error("[KronosClient] Webhook verification error:", error);
+      return false;
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Trigger Management API (Worker)
+  // ---------------------------------------------------------------------------
+  /**
+   * List triggers for a tenant user.
+   */
+  async listTriggers(params) {
+    const query = new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    });
+    return this.workerFetch(`/v1/triggers?${query.toString()}`, {
+      method: "GET"
+    });
+  }
+  /**
+   * Create a trigger.
+   * Supports NL creation (trigger_description) or manual creation (trigger_type/trigger_spec).
+   *
+   * @returns CreateTriggerResponse (accepted for NL, trigger_id for manual)
+   */
+  async createTrigger(params) {
+    const body = {
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id,
+      webhook_url: params.webhook_url,
+      webhook_secret: params.webhook_secret,
+      title: params.title,
+      action_description: params.action_description,
+      skill_id: params.skill_id,
+      skill_version_id: params.skill_version_id,
+      trigger_description: params.trigger_description,
+      trigger_type: params.trigger_type,
+      trigger_spec: params.trigger_spec,
+      next_run_at: params.next_run_at,
+      on_triggered: params.on_triggered,
+      metadata: params.metadata
+    };
+    return this.workerFetch("/v1/triggers", {
+      method: "POST",
+      json: body,
+      idempotencyKey: params.idempotencyKey
+    });
+  }
+  /**
+   * Get details for a specific trigger.
+   * Uses listTriggers and filters by trigger_id.
+   */
+  async getTriggerDetails(params) {
+    const response = await this.listTriggers({ tenant_user_id: params.tenant_user_id });
+    const trigger = response.triggers.find((t) => t.trigger_id === params.trigger_id);
+    if (!trigger) {
+      throw new KronosNotFoundError(`Trigger not found: ${params.trigger_id}`);
+    }
+    return trigger;
+  }
+  /**
+   * 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
+   */
+  async updateTrigger(params) {
+    const body = {
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id,
+      webhook_url: params.webhook_url,
+      title: params.title,
+      trigger_type: params.trigger_type,
+      trigger_spec: params.trigger_spec,
+      next_run_at: params.next_run_at,
+      action_description: params.action_description,
+      skill_id: params.skill_id,
+      skill_version_id: params.skill_version_id,
+      on_triggered: params.on_triggered,
+      status: params.status,
+      metadata: params.metadata
+    };
+    return this.workerFetch(`/v1/triggers/${params.trigger_id}`, {
+      method: "PUT",
+      json: body
+    });
+  }
+  /**
+   * Delete a trigger.
+   */
+  async deleteTrigger(params) {
+    const query = new URLSearchParams({
+      app_id: this.appId,
+      tenant_user_id: params.tenant_user_id
+    });
+    return this.workerFetch(
+      `/v1/triggers/${encodeURIComponent(params.trigger_id)}?${query.toString()}`,
+      { method: "DELETE" }
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Frontend Tokens (Server-side only)
+  // ---------------------------------------------------------------------------
+  /**
+   * 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.
+   */
+  async createFrontendToken(params) {
+    const res = await this.workerFetch(
+      "/v1/frontend-tokens",
+      {
+        method: "POST",
+        json: {
+          app_id: this.appId,
+          tenant_user_id: params.tenantUserId,
+          ttl_seconds: params.ttlSeconds,
+          ops: params.ops
+        }
+      }
+    );
+    return { token: res.token, expiresAt: res.expires_at };
+  }
+  // ---------------------------------------------------------------------------
+  // Skills API (Worker)
+  // ---------------------------------------------------------------------------
+  /**
+   * Canonical skills API with operation-based contract.
+   */
+  async manageSkill(params) {
+    const idempotencyKey = params.operation === "create" || params.operation === "update" ? params.idempotencyKey : void 0;
+    return this.workerFetch("/v1/skills/manage", {
+      method: "POST",
+      json: {
+        ...params,
+        app_id: this.appId
+      },
+      idempotencyKey
+    });
+  }
+  async resolveContextGraphSkillId(tenantUserId) {
+    const listed = await this.manageSkill({
+      operation: "list",
+      tenant_user_id: tenantUserId,
+      include_internal: true
+    });
+    const match = (listed.skills ?? []).find(
+      (skill) => skill.name === INTERNAL_CONTEXT_GRAPH_SKILL_NAME
+    );
+    return match?.skill_id ?? null;
+  }
+  parseContextGraphProcedures(files) {
+    return files.filter((file) => file.path.startsWith("procedures/") && file.path.endsWith(".md")).map((file) => {
+      const content = file.content ?? "";
+      const normalized = content.replace(/\r\n/g, "\n");
+      if (normalized.startsWith("---\n")) {
+        const endIndex = normalized.indexOf("\n---\n", 4);
+        if (endIndex !== -1) {
+          const frontmatter = normalized.slice(4, endIndex);
+          const metadata = {};
+          for (const line of frontmatter.split("\n")) {
+            const separatorIndex = line.indexOf(":");
+            if (separatorIndex === -1) continue;
+            const key = line.slice(0, separatorIndex).trim();
+            const value = line.slice(separatorIndex + 1).trim();
+            if (key && value) {
+              metadata[key] = value;
+            }
+          }
+          return {
+            title: metadata.title || (file.path.split("/").pop() ?? file.path),
+            description: metadata.description || "",
+            path: file.path
+          };
+        }
+      }
+      const lines = content.split(/\r?\n/);
+      const titleLine = lines.find((line) => line.startsWith("# "));
+      const title = titleLine ? titleLine.replace(/^#\s+/, "").trim() : file.path.split("/").pop() ?? file.path;
+      const description = lines.slice(1).map((line) => line.trim()).find((line) => line.length > 0 && !line.startsWith("#")) ?? "";
+      return {
+        title,
+        description,
+        path: file.path
+      };
+    }).sort((a, b) => a.path.localeCompare(b.path));
+  }
+  async getContextGraph(params) {
+    const skillId = await this.resolveContextGraphSkillId(params.tenant_user_id);
+    if (!skillId) {
+      return {
+        skill_id: null,
+        procedures: []
+      };
+    }
+    const treeResult = await this.manageSkill({
+      operation: "read",
+      tenant_user_id: params.tenant_user_id,
+      skill_id: skillId,
+      mode: "tree"
+    });
+    const procedurePaths = (treeResult.tree ?? []).filter((node) => node.kind === "file" && node.path.startsWith("procedures/") && node.path.endsWith(".md")).map((node) => node.path);
+    if (procedurePaths.length === 0) {
+      return {
+        skill_id: skillId,
+        procedures: []
+      };
+    }
+    const filesResult = await this.manageSkill({
+      operation: "read",
+      tenant_user_id: params.tenant_user_id,
+      skill_id: skillId,
+      mode: "files",
+      files: procedurePaths,
+      fileContent: "full"
+    });
+    return {
+      skill_id: skillId,
+      procedures: this.parseContextGraphProcedures(filesResult.files ?? [])
+    };
+  }
+  async readContextGraph(params) {
+    const skillId = await this.resolveContextGraphSkillId(params.tenant_user_id);
+    const requestedPath = params.path?.trim() || "SKILL.md";
+    if (!skillId) {
+      return {
+        skill_id: null,
+        path: requestedPath,
+        content: null
+      };
+    }
+    if (requestedPath === "SKILL.md") {
+      const result2 = await this.manageSkill({
+        operation: "read",
+        tenant_user_id: params.tenant_user_id,
+        skill_id: skillId,
+        mode: "instructions"
+      });
+      return {
+        skill_id: skillId,
+        path: "SKILL.md",
+        content: result2.instructions ?? null
+      };
+    }
+    const result = await this.manageSkill({
+      operation: "read",
+      tenant_user_id: params.tenant_user_id,
+      skill_id: skillId,
+      mode: "files",
+      files: [requestedPath],
+      fileContent: "full"
+    });
+    const file = (result.files ?? []).find((entry) => entry.path === requestedPath);
+    return {
+      skill_id: skillId,
+      path: requestedPath,
+      content: file?.content ?? null
+    };
+  }
+};
+
+// src/webhook-verification.ts
+function verifyWebhookSecret(receivedSecret, storedSecret) {
+  if (!receivedSecret || !storedSecret) {
+    return false;
+  }
+  if (receivedSecret.length !== storedSecret.length) {
+    return false;
+  }
+  let result = 0;
+  for (let i = 0; i < receivedSecret.length; i++) {
+    result |= receivedSecret.charCodeAt(i) ^ storedSecret.charCodeAt(i);
+  }
+  return result === 0;
+}
+export {
+  KronosBadRequestError,
+  KronosClient,
+  KronosError,
+  KronosForbiddenError,
+  KronosNotFoundError,
+  KronosServerError,
+  KronosUnauthorizedError,
+  generateIdempotencyKey,
+  verifyWebhookSecret
+};
+//# sourceMappingURL=index.mjs.map