@ekodb/ekodb-client 0.12.0 → 0.14.0

package/src/client.test.ts

@@ -85,7 +85,6 @@ describe("EkoDBClient configuration", () => {
     const client = new EkoDBClient({
       baseURL: "http://localhost:8080",
       apiKey: "test-key",
-      timeout: 60000,
       maxRetries: 5,
       shouldRetry: true,
       format: SerializationFormat.Json,
@@ -190,6 +189,80 @@ describe("EkoDBClient update", () => {
   });
 });
 
+// ============================================================================
+// Atomic Field Action Tests
+// ============================================================================
+
+describe("EkoDBClient updateWithAction", () => {
+  it("increments a field", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ id: "rec_1", views: 42 });
+
+    const result = await client.updateWithAction(
+      "counters",
+      "rec_1",
+      "increment",
+      "views",
+      1,
+    );
+
+    expect(result).toHaveProperty("views", 42);
+  });
+
+  it("pushes to an array field", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ id: "rec_2", tags: ["rust", "new-tag"] });
+
+    const result = await client.updateWithAction(
+      "lists",
+      "rec_2",
+      "push",
+      "tags",
+      "new-tag",
+    );
+
+    expect(result.tags).toContain("new-tag");
+  });
+
+  it("clears a field without value", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ id: "rec_3", temp: 0 });
+
+    const result = await client.updateWithAction(
+      "data",
+      "rec_3",
+      "clear",
+      "temp",
+    );
+
+    expect(result).toHaveProperty("temp", 0);
+  });
+});
+
+describe("EkoDBClient updateWithActionSequence", () => {
+  it("applies multiple actions atomically", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ id: "player_1", score: 110, lives: 2 });
+
+    const result = await client.updateWithActionSequence("game", "player_1", [
+      ["increment", "score", 10],
+      ["decrement", "lives", 1],
+      ["push", "log", "hit"],
+    ]);
+
+    expect(result).toHaveProperty("score", 110);
+    expect(result).toHaveProperty("lives", 2);
+  });
+});
+
 // ============================================================================
 // Delete Tests
 // ============================================================================
@@ -1243,3 +1316,1286 @@ describe("EkoDBClient collection utilities", () => {
     expect(result).toBe(0);
   });
 });
+
+// ============================================================================
+// Distinct Values Tests
+// ============================================================================
+
+describe("EkoDBClient distinctValues", () => {
+  it("returns distinct values for a field", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      collection: "products",
+      field: "category",
+      values: ["books", "electronics", "food"],
+      count: 3,
+    });
+
+    const result = await client.distinctValues("products", "category");
+
+    expect(result.collection).toBe("products");
+    expect(result.field).toBe("category");
+    expect(result.count).toBe(3);
+    expect(result.values).toHaveLength(3);
+    expect(result.values).toContain("books");
+  });
+
+  it("sends filter in request body", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      collection: "orders",
+      field: "status",
+      values: ["active", "pending"],
+      count: 2,
+    });
+
+    const filter = {
+      type: "Condition",
+      content: { field: "region", operator: "Eq", value: "us" },
+    };
+    const result = await client.distinctValues("orders", "status", { filter });
+
+    expect(result.count).toBe(2);
+    expect(result.values).toContain("active");
+  });
+
+  it("returns empty values for collection with no matching records", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      collection: "empty",
+      field: "tag",
+      values: [],
+      count: 0,
+    });
+
+    const result = await client.distinctValues("empty", "tag");
+
+    expect(result.count).toBe(0);
+    expect(result.values).toHaveLength(0);
+  });
+
+  it("calls correct endpoint", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({
+      collection: "users",
+      field: "role",
+      values: ["admin", "user"],
+      count: 2,
+    });
+
+    await client.distinctValues("users", "role");
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1]; // calls[0] is token
+    expect(dataCall[0]).toContain("/api/distinct/users/role");
+    expect(dataCall[1]?.method).toBe("POST");
+  });
+});
+
+// ============================================================================
+// Raw Completion Tests
+// ============================================================================
+
+describe("EkoDBClient rawCompletion", () => {
+  it("returns content from LLM response", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ content: "The answer is 42." });
+
+    const result = await client.rawCompletion({
+      system_prompt: "You are a helpful assistant.",
+      message: "What is the answer?",
+    });
+
+    expect(result.content).toBe("The answer is 42.");
+  });
+
+  it("sends all fields in request body", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ content: "Response text." });
+
+    await client.rawCompletion({
+      system_prompt: "System.",
+      message: "User.",
+      provider: "openai",
+      model: "gpt-4o",
+      max_tokens: 512,
+    });
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1]; // calls[0] is token
+    const body = JSON.parse(dataCall[1]?.body as string);
+    expect(body.system_prompt).toBe("System.");
+    expect(body.message).toBe("User.");
+    expect(body.provider).toBe("openai");
+    expect(body.model).toBe("gpt-4o");
+    expect(body.max_tokens).toBe(512);
+  });
+
+  it("omits optional fields when not provided", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ content: "Response." });
+
+    await client.rawCompletion({
+      system_prompt: "System.",
+      message: "User.",
+    });
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    const body = JSON.parse(dataCall[1]?.body as string);
+    expect(body.provider).toBeUndefined();
+    expect(body.model).toBeUndefined();
+    expect(body.max_tokens).toBeUndefined();
+  });
+
+  it("calls correct endpoint with POST method", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ content: "Response." });
+
+    await client.rawCompletion({
+      system_prompt: "System.",
+      message: "User.",
+    });
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/chat/complete");
+    expect(dataCall[1]?.method).toBe("POST");
+  });
+});
+
+// ============================================================================
+// rawCompletionStream (SSE) Tests
+// ============================================================================
+
+describe("EkoDBClient rawCompletionStream", () => {
+  it("parses SSE done event and returns content", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    // SSE response with token chunks and a done event
+    const sseBody = [
+      'data: {"token":"Hello"}',
+      'data: {"token":" world"}',
+      'data: {"content":"Hello world","done":true}',
+      "",
+    ].join("\n");
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers(),
+    });
+
+    const result = await client.rawCompletionStream({
+      system_prompt: "System.",
+      message: "User.",
+    });
+
+    expect(result.content).toBe("Hello world");
+  });
+
+  it("accumulates tokens when no done event", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    const sseBody = [
+      'data: {"token":"chunk1"}',
+      'data: {"token":"chunk2"}',
+      "",
+    ].join("\n");
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers(),
+    });
+
+    const result = await client.rawCompletionStream({
+      system_prompt: "System.",
+      message: "User.",
+    });
+
+    expect(result.content).toBe("chunk1chunk2");
+  });
+
+  it("throws on SSE error event", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    const sseBody = 'data: {"error":"LLM timeout"}\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers(),
+    });
+
+    await expect(
+      client.rawCompletionStream({
+        system_prompt: "System.",
+        message: "User.",
+      }),
+    ).rejects.toThrow("LLM timeout");
+  });
+
+  it("throws on non-200 HTTP response", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      text: async () => "Unauthorized",
+      headers: new Headers(),
+    });
+
+    await expect(
+      client.rawCompletionStream({
+        system_prompt: "System.",
+        message: "User.",
+      }),
+    ).rejects.toThrow("401");
+  });
+
+  it("calls the /stream endpoint", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => 'data: {"content":"ok"}\n',
+      headers: new Headers(),
+    });
+
+    await client.rawCompletionStream({
+      system_prompt: "System.",
+      message: "User.",
+    });
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/chat/complete/stream");
+    expect(dataCall[1]?.headers?.Accept).toBe("text/event-stream");
+  });
+});
+
+// ============================================================================
+// Token Management Tests
+// ============================================================================
+
+describe("refreshToken", () => {
+  it("fetches a new token", async () => {
+    const client = createTestClient();
+
+    // First token fetch (init)
+    mockTokenResponse();
+    mockJsonResponse({ status: "ok" });
+    await client.health();
+
+    // Refresh token
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ token: "new-jwt-token" }),
+      headers: new Headers(),
+    });
+    await client.refreshToken();
+
+    // Verify it called the token endpoint again
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const tokenCalls = calls.filter((c: unknown[]) =>
+      (c[0] as string).includes("/api/auth/token"),
+    );
+    expect(tokenCalls.length).toBe(2);
+  });
+});
+
+describe("clearTokenCache", () => {
+  it("clears the cached token", async () => {
+    const client = createTestClient();
+
+    // Init with token
+    mockTokenResponse();
+    mockJsonResponse({ status: "ok" });
+    await client.health();
+
+    // Clear cache
+    client.clearTokenCache();
+
+    // Next request should fetch a new token
+    mockTokenResponse();
+    mockJsonResponse({ status: "ok" });
+    await client.health();
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const tokenCalls = calls.filter((c: unknown[]) =>
+      (c[0] as string).includes("/api/auth/token"),
+    );
+    expect(tokenCalls.length).toBe(2);
+  });
+});
+
+// ============================================================================
+// findByIdWithProjection Tests
+// ============================================================================
+
+describe("findByIdWithProjection", () => {
+  it("calls correct endpoint with select_fields", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ id: "123", name: "Alice" });
+
+    await client.findByIdWithProjection("users", "123", ["name", "email"]);
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/find/users/123");
+    expect(dataCall[0]).toContain("select_fields=name%2Cemail");
+  });
+
+  it("calls correct endpoint with exclude_fields", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ id: "123", name: "Alice" });
+
+    await client.findByIdWithProjection("users", "123", undefined, [
+      "password",
+    ]);
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("exclude_fields=password");
+  });
+
+  it("calls without params when no projection", async () => {
+    const client = createTestClient();
+
+    mockTokenResponse();
+    mockJsonResponse({ id: "123", name: "Alice" });
+
+    await client.findByIdWithProjection("users", "123");
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toBe("http://localhost:8080/api/find/users/123");
+  });
+});
+
+// ============================================================================
+// Goal CRUD Tests
+// ============================================================================
+
+describe("EkoDBClient goals", () => {
+  it("creates a goal", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1", title: "Test Goal", status: "active" });
+
+    const result = await client.goalCreate({ title: "Test Goal" });
+    expect(result).toHaveProperty("id", "goal_1");
+    expect(result).toHaveProperty("status", "active");
+  });
+
+  it("lists goals", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ goals: [{ id: "goal_1" }, { id: "goal_2" }] });
+
+    const result = await client.goalList();
+    expect(result).toHaveProperty("goals");
+  });
+
+  it("gets a goal by ID", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1", title: "Test Goal" });
+
+    const result = await client.goalGet("goal_1");
+    expect(result).toHaveProperty("id", "goal_1");
+  });
+
+  it("updates a goal", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1", title: "Updated" });
+
+    const result = await client.goalUpdate("goal_1", { title: "Updated" });
+    expect(result).toHaveProperty("title", "Updated");
+  });
+
+  it("deletes a goal", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await expect(client.goalDelete("goal_1")).resolves.not.toThrow();
+  });
+
+  it("searches goals", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ goals: [{ id: "goal_1" }] });
+
+    const result = await client.goalSearch("test query");
+    expect(result).toHaveProperty("goals");
+  });
+
+  it("completes a goal", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1", status: "pending_review" });
+
+    const result = await client.goalComplete("goal_1", { summary: "Done" });
+    expect(result).toHaveProperty("status", "pending_review");
+  });
+
+  it("approves a goal", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1", status: "in_progress" });
+
+    const result = await client.goalApprove("goal_1");
+    expect(result).toHaveProperty("status", "in_progress");
+  });
+
+  it("rejects a goal", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1", status: "failed" });
+
+    const result = await client.goalReject("goal_1", { reason: "Bad plan" });
+    expect(result).toHaveProperty("status", "failed");
+  });
+
+  it("starts a goal step", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1" });
+
+    const result = await client.goalStepStart("goal_1", 0);
+    expect(result).toHaveProperty("id", "goal_1");
+  });
+
+  it("completes a goal step", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1" });
+
+    const result = await client.goalStepComplete("goal_1", 0, {
+      result: "Step done",
+    });
+    expect(result).toHaveProperty("id", "goal_1");
+  });
+
+  it("fails a goal step", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "goal_1" });
+
+    const result = await client.goalStepFail("goal_1", 0, {
+      error: "Step failed",
+    });
+    expect(result).toHaveProperty("id", "goal_1");
+  });
+
+  it("returns error for non-existent goal", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockErrorResponse(404, "Not Found");
+
+    await expect(client.goalGet("nonexistent")).rejects.toThrow();
+  });
+});
+
+// ============================================================================
+// Task CRUD Tests
+// ============================================================================
+
+describe("EkoDBClient tasks", () => {
+  it("creates a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", name: "Test Task", status: "active" });
+
+    const result = await client.taskCreate({
+      name: "Test Task",
+      cron: "0 * * * *",
+    });
+    expect(result).toHaveProperty("id", "task_1");
+  });
+
+  it("lists tasks", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ tasks: [] });
+
+    const result = await client.taskList();
+    expect(result).toHaveProperty("tasks");
+  });
+
+  it("gets a task by ID", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", name: "Test Task" });
+
+    const result = await client.taskGet("task_1");
+    expect(result).toHaveProperty("id", "task_1");
+  });
+
+  it("updates a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", name: "Updated" });
+
+    const result = await client.taskUpdate("task_1", { name: "Updated" });
+    expect(result).toHaveProperty("name", "Updated");
+  });
+
+  it("deletes a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await expect(client.taskDelete("task_1")).resolves.not.toThrow();
+  });
+
+  it("gets due tasks", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ tasks: [] });
+
+    const result = await client.taskDue("2026-03-20T00:00:00Z");
+    expect(result).toHaveProperty("tasks");
+  });
+
+  it("starts a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", status: "running" });
+
+    const result = await client.taskStart("task_1");
+    expect(result).toHaveProperty("status", "running");
+  });
+
+  it("succeeds a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", status: "active" });
+
+    const result = await client.taskSucceed("task_1", { output: "Success" });
+    expect(result).toHaveProperty("status", "active");
+  });
+
+  it("fails a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", status: "active" });
+
+    const result = await client.taskFail("task_1", { error: "Timeout" });
+    expect(result).toHaveProperty("status", "active");
+  });
+
+  it("pauses a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", status: "paused" });
+
+    const result = await client.taskPause("task_1");
+    expect(result).toHaveProperty("status", "paused");
+  });
+
+  it("resumes a task", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "task_1", status: "active" });
+
+    const result = await client.taskResume("task_1", {});
+    expect(result).toHaveProperty("status", "active");
+  });
+});
+
+// ============================================================================
+// Agent CRUD Tests
+// ============================================================================
+
+describe("EkoDBClient agents", () => {
+  it("creates an agent", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "agent_1", name: "TestAgent" });
+
+    const result = await client.agentCreate({
+      name: "TestAgent",
+      system_prompt: "You help.",
+    });
+    expect(result).toHaveProperty("name", "TestAgent");
+  });
+
+  it("lists agents", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ agents: [] });
+
+    const result = await client.agentList();
+    expect(result).toHaveProperty("agents");
+  });
+
+  it("gets an agent by ID", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "agent_1", name: "TestAgent" });
+
+    const result = await client.agentGet("agent_1");
+    expect(result).toHaveProperty("id", "agent_1");
+  });
+
+  it("gets an agent by name", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "agent_1", name: "TestAgent" });
+
+    const result = await client.agentGetByName("TestAgent");
+    expect(result).toHaveProperty("name", "TestAgent");
+  });
+
+  it("updates an agent", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "agent_1", name: "Updated" });
+
+    const result = await client.agentUpdate("agent_1", { name: "Updated" });
+    expect(result).toHaveProperty("name", "Updated");
+  });
+
+  it("deletes an agent", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await expect(client.agentDelete("agent_1")).resolves.not.toThrow();
+  });
+
+  it("gets agents by deployment", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ agents: [{ id: "agent_1" }] });
+
+    const result = await client.agentsByDeployment("deploy_1");
+    expect(result).toHaveProperty("agents");
+  });
+
+  it("returns error for non-existent agent", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockErrorResponse(404, "Not Found");
+
+    await expect(client.agentGet("nonexistent")).rejects.toThrow();
+  });
+});
+
+// ============================================================================
+// rawCompletionStreamWithProgress Tests
+// ============================================================================
+
+describe("EkoDBClient rawCompletionStreamWithProgress", () => {
+  it("calls onToken for each token", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    // Mock SSE response
+    const sseBody = [
+      'data: {"token": "Hello"}',
+      'data: {"token": " World"}',
+      'data: {"content": "Hello World"}',
+    ].join("\n");
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const tokens: string[] = [];
+    const result = await client.rawCompletionStreamWithProgress(
+      { system_prompt: "test", message: "test" },
+      (token) => tokens.push(token),
+    );
+
+    expect(tokens).toEqual(["Hello", " World"]);
+    expect(result.content).toBe("Hello World");
+  });
+
+  it("throws on SSE error event", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody = 'data: {"error": "Model overloaded"}';
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const tokens: string[] = [];
+    await expect(
+      client.rawCompletionStreamWithProgress(
+        { system_prompt: "test", message: "test" },
+        (token) => tokens.push(token),
+      ),
+    ).rejects.toThrow("Model overloaded");
+  });
+});
+
+// ============================================================================
+// Goal Template CRUD Tests
+// ============================================================================
+
+describe("EkoDBClient goal templates", () => {
+  it("creates a goal template", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "gt_1", title: "Deploy Checklist" });
+
+    const result = await client.goalTemplateCreate({
+      title: "Deploy Checklist",
+      steps: [{ title: "Run tests" }],
+    });
+    expect(result).toHaveProperty("id", "gt_1");
+    expect(result).toHaveProperty("title", "Deploy Checklist");
+  });
+
+  it("creates a goal template and verifies POST method", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "gt_2", title: "Onboarding" });
+
+    await client.goalTemplateCreate({ title: "Onboarding" });
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1]; // calls[0] is token
+    expect(dataCall[0]).toContain("/api/chat/goal-templates");
+    expect(dataCall[1]?.method).toBe("POST");
+  });
+
+  it("lists goal templates", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      templates: [{ id: "gt_1" }, { id: "gt_2" }],
+    });
+
+    const result = await client.goalTemplateList();
+    expect(result).toHaveProperty("templates");
+  });
+
+  it("lists goal templates and verifies GET method", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ templates: [] });
+
+    await client.goalTemplateList();
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/chat/goal-templates");
+    expect(dataCall[1]?.method).toBe("GET");
+  });
+
+  it("gets a goal template by ID", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "gt_1", title: "Deploy Checklist" });
+
+    const result = await client.goalTemplateGet("gt_1");
+    expect(result).toHaveProperty("id", "gt_1");
+    expect(result).toHaveProperty("title", "Deploy Checklist");
+  });
+
+  it("gets a goal template and verifies endpoint", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "gt_1", title: "Deploy Checklist" });
+
+    await client.goalTemplateGet("gt_1");
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/chat/goal-templates/gt_1");
+    expect(dataCall[1]?.method).toBe("GET");
+  });
+
+  it("updates a goal template", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "gt_1", title: "Updated Checklist" });
+
+    const result = await client.goalTemplateUpdate("gt_1", {
+      title: "Updated Checklist",
+    });
+    expect(result).toHaveProperty("title", "Updated Checklist");
+  });
+
+  it("updates a goal template and verifies PUT method", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "gt_1", title: "Updated" });
+
+    await client.goalTemplateUpdate("gt_1", { title: "Updated" });
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/chat/goal-templates/gt_1");
+    expect(dataCall[1]?.method).toBe("PUT");
+  });
+
+  it("deletes a goal template", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await expect(client.goalTemplateDelete("gt_1")).resolves.not.toThrow();
+  });
+
+  it("deletes a goal template and verifies DELETE method", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await client.goalTemplateDelete("gt_1");
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/chat/goal-templates/gt_1");
+    expect(dataCall[1]?.method).toBe("DELETE");
+  });
+
+  it("returns error for non-existent goal template", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockErrorResponse(404, "Not Found");
+
+    await expect(client.goalTemplateGet("nonexistent")).rejects.toThrow();
+  });
+});
+
+// ============================================================================
+// chatMessageStream (SSE) Tests
+// ============================================================================
+
+describe("EkoDBClient chatMessageStream", () => {
+  it("emits chunk and end events from SSE stream", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody = [
+      'data: {"token":"Hello"}',
+      'data: {"token":" world"}',
+      'data: {"content":"Hello world","message_id":"msg_1","execution_time_ms":42}',
+      "",
+    ].join("\n");
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    // Wait for the async SSE processing to complete
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toHaveLength(3);
+    expect(events[0]).toEqual({ type: "chunk", content: "Hello" });
+    expect(events[1]).toEqual({ type: "chunk", content: " world" });
+    expect(events[2].type).toBe("end");
+    expect(events[2].messageId).toBe("msg_1");
+    expect(events[2].executionTimeMs).toBe(42);
+  });
+
+  it("emits error event on SSE error", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    const sseBody = 'data: {"error":"LLM timeout"}\n';
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => sseBody,
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toEqual({ type: "error", error: "LLM timeout" });
+  });
+
+  it("emits error event on non-200 HTTP response", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    mockFetch.mockResolvedValueOnce({
+      ok: false,
+      status: 401,
+      text: async () => "Unauthorized",
+      headers: new Headers(),
+    });
+
+    const events: any[] = [];
+    const stream = client.chatMessageStream("chat_123", {
+      message: "Hello",
+    });
+    stream.on("event", (evt: any) => events.push(evt));
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(events).toHaveLength(1);
+    expect(events[0].type).toBe("error");
+    expect(events[0].error).toContain("401");
+  });
+
+  it("calls the correct stream endpoint", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      text: async () => 'data: {"token":"ok"}\n',
+      headers: new Headers({ "content-type": "text/event-stream" }),
+    });
+
+    client.chatMessageStream("chat_456", { message: "Test" });
+
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    const calls = (global.fetch as ReturnType<typeof vi.fn>).mock.calls;
+    const dataCall = calls[1];
+    expect(dataCall[0]).toContain("/api/chat/chat_456/messages/stream");
+    expect(dataCall[1]?.method).toBe("POST");
+    expect(dataCall[1]?.headers?.Accept).toBe("text/event-stream");
+  });
+});
+
+// ============================================================================
+// Schedule CRUD Tests
+// ============================================================================
+
+describe("EkoDBClient schedules", () => {
+  it("creates a schedule", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      id: "sched_1",
+      name: "Nightly Backup",
+      cron: "0 2 * * *",
+      status: "active",
+    });
+
+    const result = await client.createSchedule({
+      name: "Nightly Backup",
+      cron: "0 2 * * *",
+      action: "backup",
+    });
+    expect(result).toHaveProperty("id", "sched_1");
+    expect(result).toHaveProperty("status", "active");
+  });
+
+  it("lists schedules", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      schedules: [
+        { id: "sched_1", name: "Nightly Backup" },
+        { id: "sched_2", name: "Hourly Sync" },
+      ],
+    });
+
+    const result = await client.listSchedules();
+    expect(result).toHaveProperty("schedules");
+  });
+
+  it("gets a schedule by ID", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      id: "sched_1",
+      name: "Nightly Backup",
+      cron: "0 2 * * *",
+    });
+
+    const result = await client.getSchedule("sched_1");
+    expect(result).toHaveProperty("id", "sched_1");
+    expect(result).toHaveProperty("name", "Nightly Backup");
+  });
+
+  it("updates a schedule", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      id: "sched_1",
+      name: "Updated Backup",
+      cron: "0 3 * * *",
+    });
+
+    const result = await client.updateSchedule("sched_1", {
+      name: "Updated Backup",
+      cron: "0 3 * * *",
+    });
+    expect(result).toHaveProperty("name", "Updated Backup");
+    expect(result).toHaveProperty("cron", "0 3 * * *");
+  });
+
+  it("deletes a schedule", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({});
+
+    await expect(client.deleteSchedule("sched_1")).resolves.not.toThrow();
+  });
+
+  it("pauses a schedule", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "sched_1", status: "paused" });
+
+    const result = await client.pauseSchedule("sched_1");
+    expect(result).toHaveProperty("status", "paused");
+  });
+
+  it("resumes a schedule", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ id: "sched_1", status: "active" });
+
+    const result = await client.resumeSchedule("sched_1");
+    expect(result).toHaveProperty("status", "active");
+  });
+});
+
+// ============================================================================
+// KV Links Tests
+// ============================================================================
+
+describe("EkoDBClient kv links", () => {
+  it("gets links for a KV key", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      links: [
+        { collection: "users", document_id: "user_1" },
+        { collection: "orders", document_id: "order_1" },
+      ],
+    });
+
+    const result = await client.kvGetLinks("session:user123");
+    expect(result).toHaveProperty("links");
+  });
+
+  it("links a document to a KV key", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ status: "linked" });
+
+    const result = await client.kvLink("session:user123", "users", "user_1");
+    expect(result).toHaveProperty("status", "linked");
+  });
+
+  it("unlinks a document from a KV key", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({ status: "unlinked" });
+
+    const result = await client.kvUnlink("session:user123", "users", "user_1");
+    expect(result).toHaveProperty("status", "unlinked");
+  });
+});
+
+// ============================================================================
+// Text Search and Hybrid Search Tests
+// ============================================================================
+
+describe("EkoDBClient text and hybrid search", () => {
+  it("performs text search", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      results: [
+        {
+          record: { id: "doc_1", title: "Ownership Guide" },
+          score: 0.92,
+          matched_fields: ["title"],
+        },
+        {
+          record: { id: "doc_2", title: "Property Ownership" },
+          score: 0.85,
+          matched_fields: ["title"],
+        },
+      ],
+      total: 2,
+      took_ms: 12,
+    });
+
+    const result = await client.textSearch("documents", "ownership", {
+      limit: 10,
+      select_fields: ["title", "content"],
+    });
+
+    expect(result.results).toHaveLength(2);
+    expect(result.total).toBe(2);
+    expect(result.results[0].score).toBe(0.92);
+  });
+
+  it("performs hybrid search", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    mockJsonResponse({
+      results: [
+        {
+          record: { id: "doc_1", title: "ML Guide", content: "Learn ML" },
+          score: 0.95,
+          matched_fields: ["title", "content"],
+        },
+      ],
+      total: 1,
+      took_ms: 25,
+    });
+
+    const queryVector = [0.1, 0.2, 0.3, 0.4, 0.5];
+    const result = await client.hybridSearch(
+      "documents",
+      "machine learning",
+      queryVector,
+      5,
+    );
+
+    expect(result).toHaveLength(1);
+    expect(result[0]).toHaveProperty("id", "doc_1");
+    expect(result[0]).toHaveProperty("title", "ML Guide");
+  });
+});
+
+// ============================================================================
+// Auth Token Management
+// ============================================================================
+
+describe("EkoDBClient auth token management", () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  it("getToken auto-refreshes when token is about to expire", async () => {
+    const client = createTestClient();
+
+    // First init — get a token with a short expiry (30s from now)
+    const shortExp = Math.floor(Date.now() / 1000) + 30;
+    const shortPayload = btoa(JSON.stringify({ exp: shortExp }))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=/g, "");
+    const shortJwt = `eyJhbGciOiJIUzI1NiJ9.${shortPayload}.fakesig`;
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ token: shortJwt }),
+      headers: new Headers(),
+    });
+    await client.init();
+
+    // Now getToken should see it's about to expire and refresh
+    const newExp = Math.floor(Date.now() / 1000) + 3600;
+    const newPayload = btoa(JSON.stringify({ exp: newExp }))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=/g, "");
+    const newJwt = `eyJhbGciOiJIUzI1NiJ9.${newPayload}.fakesig`;
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ token: newJwt }),
+      headers: new Headers(),
+    });
+
+    const token = await client.getToken();
+    expect(token).toBe(newJwt);
+    // 2 fetch calls: init + proactive refresh
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+
+  it("getToken returns cached token when not expired", async () => {
+    const client = createTestClient();
+
+    // Token with expiry far in the future
+    const farExp = Math.floor(Date.now() / 1000) + 7200;
+    const payload = btoa(JSON.stringify({ exp: farExp }))
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=/g, "");
+    const jwt = `eyJhbGciOiJIUzI1NiJ9.${payload}.fakesig`;
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => ({ token: jwt }),
+      headers: new Headers(),
+    });
+    await client.init();
+
+    // getToken should return cached — no extra fetch
+    const token = await client.getToken();
+    expect(token).toBe(jwt);
+    expect(mockFetch).toHaveBeenCalledTimes(1); // only init
+  });
+
+  it("clearTokenCache resets token and expiry", async () => {
+    const client = createTestClient();
+    mockTokenResponse();
+    await client.init();
+    expect(await client.getToken()).toBeTruthy();
+
+    client.clearTokenCache();
+    // After clear, getToken will auto-refresh (fetch a new token)
+    mockTokenResponse();
+    const token = await client.getToken();
+    expect(token).toBe("test-jwt-token");
+    // 2 fetch calls: init + post-clear getToken refresh
+    expect(mockFetch).toHaveBeenCalledTimes(2);
+  });
+});