@kognitivedev/cloud-web-search 0.2.28

package/src/__tests__/client.test.ts

@@ -0,0 +1,784 @@
+import { describe, expect, it, vi } from "vitest";
+import { HttpTransport } from "@kognitivedev/client-core";
+import {
+    CloudWebSearchValidationError,
+    KognitiveCloudWebSearchClient,
+    toCloudWebSearchRichEvents,
+} from "../index";
+
+function toSSEPayload(events: Array<{
+    event?: string;
+    id?: string;
+    retry?: number;
+    data: unknown;
+}>) {
+    return events.map((entry) => {
+        const lines: string[] = [];
+        if (entry.id) {
+            lines.push(`id: ${entry.id}`);
+        }
+        if (entry.retry !== undefined) {
+            lines.push(`retry: ${entry.retry}`);
+        }
+        if (entry.event) {
+            lines.push(`event: ${entry.event}`);
+        }
+        lines.push(`data: ${JSON.stringify(entry.data)}`);
+        lines.push("");
+        return lines.join("\n");
+    }).join("\n");
+}
+
+function toReadableStream(payload: string) {
+    const encoder = new TextEncoder();
+    return new ReadableStream<Uint8Array>({
+        start(controller) {
+            controller.enqueue(encoder.encode(payload));
+            controller.close();
+        },
+    });
+}
+
+async function collect<T>(iterable: AsyncIterable<T>): Promise<T[]> {
+    const values: T[] = [];
+    for await (const value of iterable) {
+        values.push(value);
+    }
+    return values;
+}
+
+function createProgress(overrides: Partial<Record<keyof ReturnType<typeof baseProgress>, unknown>> = {}) {
+    return {
+        ...baseProgress(),
+        ...overrides,
+    };
+}
+
+function baseProgress() {
+    return {
+        stage: "queued",
+        message: "Web-search job created",
+        timestamp: "2026-04-22T10:00:00.000Z",
+    };
+}
+
+function createJob(overrides: Record<string, unknown> = {}) {
+    return {
+        id: "job_123",
+        projectId: "project_123",
+        mode: "search",
+        searchQuery: "latest Bun release notes",
+        searchInstructions: null,
+        responseInstructions: null,
+        responseSchema: null,
+        researchPlan: null,
+        parameters: {},
+        status: "queued",
+        results: null,
+        progress: [],
+        errorMessage: null,
+        cancelRequestedAt: null,
+        cancelledAt: null,
+        createdAt: "2026-04-22T10:00:00.000Z",
+        updatedAt: "2026-04-22T10:00:00.000Z",
+        ...overrides,
+    };
+}
+
+function createJobEvent(overrides: Record<string, unknown> = {}) {
+    return {
+        id: "evt_1",
+        jobId: "job_123",
+        projectId: "project_123",
+        eventType: "job.started",
+        stage: "dispatching",
+        status: "in_progress",
+        message: "Queued web-search job for execution",
+        payload: {},
+        createdAt: "2026-04-22T10:00:01.000Z",
+        ...overrides,
+    };
+}
+
+function parseSummary(value: unknown): { summary: string; markdown?: string } {
+    if (!value || typeof value !== "object" || Array.isArray(value) || typeof (value as { summary?: unknown }).summary !== "string") {
+        throw new Error("Expected { summary: string }");
+    }
+    return {
+        summary: (value as { summary: string }).summary,
+        ...((value as { markdown?: unknown }).markdown && typeof (value as { markdown?: unknown }).markdown === "string"
+            ? { markdown: (value as { markdown: string }).markdown }
+            : {}),
+    };
+}
+
+describe("@kognitivedev/cloud-web-search client", () => {
+    it("validates outgoing create inputs and decodes list/create responses", async () => {
+        const json = vi.fn()
+            .mockResolvedValueOnce({
+                jobs: [createJob()],
+            })
+            .mockResolvedValueOnce(createJob({
+                id: "job_456",
+                status: "queued",
+                parameters: { maxPages: 4 },
+            }));
+        const transport = {
+            baseUrl: "https://api.kognitive.dev",
+            json,
+            raw: vi.fn(),
+            poll: vi.fn(),
+        } as unknown as HttpTransport;
+
+        const client = new KognitiveCloudWebSearchClient(transport);
+
+        await expect(client.jobs.list()).resolves.toEqual([createJob()]);
+        await expect(client.jobs.createSearch("latest Bun release notes", { maxPages: 4 })).resolves.toMatchObject({
+            id: "job_456",
+            projectId: "project_123",
+            status: "queued",
+            parameters: { maxPages: 4 },
+        });
+
+        await expect(client.jobs.create({
+            mode: "search",
+            query: "   ",
+        })).rejects.toBeInstanceOf(CloudWebSearchValidationError);
+
+        expect(json).toHaveBeenNthCalledWith(1, "/api/cloud/web-search/jobs");
+        expect(json).toHaveBeenNthCalledWith(2, "/api/cloud/web-search/jobs", {
+            method: "POST",
+            body: JSON.stringify({
+                mode: "search",
+                query: "latest Bun release notes",
+                parameters: { maxPages: 4 },
+            }),
+        });
+    });
+
+    it("waits for completion and decodes structured output with parseOutput", async () => {
+        const json = vi.fn().mockResolvedValue({
+            jobId: "job_123",
+            status: "completed",
+            result: {
+                output: { summary: "done" },
+                text: "done",
+                sources: [{ title: "Source", url: "https://example.com/source", faviconUrl: "https://example.com/favicon.ico" }],
+            },
+        });
+        const poll = vi.fn().mockResolvedValue(createJob({
+            status: "completed",
+            mode: "research",
+            searchQuery: null,
+            searchInstructions: "Research Bun updates",
+            responseSchema: {
+                type: "object",
+                properties: {
+                    summary: { type: "string" },
+                },
+            },
+        }));
+        const transport = {
+            baseUrl: "https://api.kognitive.dev",
+            json,
+            raw: vi.fn(),
+            poll,
+        } as unknown as HttpTransport;
+
+        const client = new KognitiveCloudWebSearchClient(transport);
+        const result = await client.jobs.waitForCompletion("job_123", {
+            intervalMs: 250,
+            timeoutMs: 5_000,
+            parseOutput: parseSummary,
+        });
+
+        expect(poll).toHaveBeenCalledTimes(1);
+        expect(result.job.status).toBe("completed");
+        expect(result.result?.output).toEqual({ summary: "done" });
+        expect(result.result?.sources[0]?.faviconUrl).toBe("https://example.com/favicon.ico");
+        expect(json).toHaveBeenCalledWith("/api/cloud/web-search/jobs/job_123/result");
+    });
+
+    it("normalizes replayed backend event logs, dedupes snapshot progress, and parses typed results", async () => {
+        const raw = vi.fn().mockResolvedValue(new Response(toReadableStream(toSSEPayload([
+            {
+                event: "job.snapshot",
+                data: {
+                    job: createJob({
+                        mode: "research",
+                        searchQuery: null,
+                        searchInstructions: "Research Bun updates",
+                        responseSchema: {
+                            type: "object",
+                            properties: {
+                                summary: { type: "string" },
+                            },
+                        },
+                        status: "in_progress",
+                        progress: [
+                            createProgress(),
+                        ],
+                        updatedAt: "2026-04-22T10:00:00.000Z",
+                    }),
+                },
+            },
+            {
+                event: "job.created",
+                data: createJobEvent({
+                    id: "evt_queued",
+                    eventType: "job.created",
+                    stage: "queued",
+                    status: "queued",
+                    message: "Web-search job created",
+                    payload: { mode: "research" },
+                    createdAt: "2026-04-22T10:00:00.000Z",
+                }),
+            },
+            {
+                event: "websearch.research.plan.started",
+                data: createJobEvent({
+                    id: "evt_plan",
+                    eventType: "websearch.research.plan.started",
+                    stage: "planning",
+                    status: "in_progress",
+                    message: "Building research plan",
+                    payload: { step: "plan" },
+                    createdAt: "2026-04-22T10:00:01.000Z",
+                }),
+            },
+            {
+                event: "websearch.research.reasoning",
+                data: createJobEvent({
+                    id: "evt_reasoning",
+                    eventType: "websearch.research.reasoning",
+                    stage: null,
+                    status: "in_progress",
+                    message: null,
+                    payload: { delta: "Thinking..." },
+                    createdAt: "2026-04-22T10:00:01.500Z",
+                }),
+            },
+            {
+                event: "job.completed",
+                data: createJobEvent({
+                    id: "evt_completed",
+                    eventType: "job.completed",
+                    stage: "completed",
+                    status: "completed",
+                    message: "Web-search job completed",
+                    payload: {
+                        runId: "run_123",
+                        result: {
+                            output: { summary: "Ready" },
+                            text: "Ready",
+                            sources: [],
+                        },
+                    },
+                    createdAt: "2026-04-22T10:00:02.000Z",
+                }),
+            },
+        ]))));
+        const transport = {
+            baseUrl: "https://api.kognitive.dev",
+            json: vi.fn(),
+            raw,
+            poll: vi.fn(),
+        } as unknown as HttpTransport;
+
+        const client = new KognitiveCloudWebSearchClient(transport);
+        const stream = await client.jobs.subscribe("job_123", {
+            parseOutput: parseSummary,
+        });
+        const events = await collect(stream);
+
+        expect(raw).toHaveBeenCalledWith("/api/cloud/web-search/jobs/job_123/events/stream", undefined);
+        expect(events).toHaveLength(5);
+        expect(events[0]).toMatchObject({
+            type: "snapshot",
+            job: {
+                id: "job_123",
+                status: "in_progress",
+            },
+        });
+        expect(events[1]).toMatchObject({
+            type: "progress",
+            replay: true,
+            progress: {
+                stage: "queued",
+                message: "Web-search job created",
+            },
+        });
+        expect(events[2]).toMatchObject({
+            type: "progress",
+            eventId: "evt_plan",
+            rawEventType: "websearch.research.plan.started",
+            progress: {
+                stage: "planning",
+                message: "Building research plan",
+            },
+        });
+        expect(events[3]).toMatchObject({
+            type: "event",
+            event: {
+                eventType: "websearch.research.reasoning",
+            },
+        });
+        expect(events[4]).toMatchObject({
+            type: "completed",
+            eventId: "evt_completed",
+            jobId: "job_123",
+            result: {
+                output: { summary: "Ready" },
+                text: "Ready",
+                sources: [],
+            },
+        });
+    });
+
+    it("parses canonical lifecycle frames and surfaces unknown events", async () => {
+        const raw = vi.fn().mockResolvedValue(new Response(toReadableStream(toSSEPayload([
+            {
+                event: "job.snapshot",
+                data: {
+                    job: createJob({
+                        status: "in_progress",
+                    }),
+                },
+            },
+            {
+                id: "evt_progress",
+                event: "job.progress",
+                data: {
+                    jobId: "job_123",
+                    status: "in_progress",
+                    progress: {
+                        stage: "searching",
+                        message: "Executing hosted search",
+                        timestamp: "2026-04-22T10:00:01.000Z",
+                    },
+                },
+            },
+            {
+                event: "custom.opaque",
+                data: "opaque",
+            },
+            {
+                id: "evt_completed",
+                event: "job.completed",
+                data: {
+                    job: createJob({
+                        status: "completed",
+                        updatedAt: "2026-04-22T10:00:02.000Z",
+                    }),
+                    result: {
+                        text: "Done",
+                        sources: [],
+                    },
+                },
+            },
+        ]))));
+        const transport = {
+            baseUrl: "https://api.kognitive.dev",
+            json: vi.fn(),
+            raw,
+            poll: vi.fn(),
+        } as unknown as HttpTransport;
+
+        const client = new KognitiveCloudWebSearchClient(transport);
+        const stream = await client.jobs.subscribe("job_123");
+        const events = await collect(stream);
+
+        expect(events).toHaveLength(4);
+        expect(events[1]).toMatchObject({
+            type: "progress",
+            eventId: "evt_progress",
+            progress: {
+                stage: "searching",
+                message: "Executing hosted search",
+            },
+        });
+        expect(events[2]).toMatchObject({
+            type: "unknown",
+            frame: {
+                event: "custom.opaque",
+                data: "opaque",
+            },
+        });
+        expect(events[3]).toMatchObject({
+            type: "completed",
+            eventId: "evt_completed",
+            result: {
+                text: "Done",
+                sources: [],
+            },
+        });
+    });
+
+    it("throws validation errors for malformed server payloads", async () => {
+        const transport = {
+            baseUrl: "https://api.kognitive.dev",
+            json: vi.fn().mockResolvedValue({
+                jobs: [{ id: "job_123" }],
+            }),
+            raw: vi.fn(),
+            poll: vi.fn(),
+        } as unknown as HttpTransport;
+
+        const client = new KognitiveCloudWebSearchClient(transport);
+        await expect(client.jobs.list()).rejects.toBeInstanceOf(CloudWebSearchValidationError);
+    });
+
+    it("fails fast for malformed canonical lifecycle frames", async () => {
+        const raw = vi.fn().mockResolvedValue(new Response(toReadableStream(toSSEPayload([
+            {
+                event: "job.snapshot",
+                data: {
+                    job: createJob({
+                        status: "in_progress",
+                    }),
+                },
+            },
+            {
+                event: "job.completed",
+                data: {
+                    bad: true,
+                },
+            },
+        ]))));
+        const transport = {
+            baseUrl: "https://api.kognitive.dev",
+            json: vi.fn(),
+            raw,
+            poll: vi.fn(),
+        } as unknown as HttpTransport;
+
+        const client = new KognitiveCloudWebSearchClient(transport);
+        const stream = await client.jobs.subscribe("job_123");
+
+        await expect(collect(stream)).rejects.toBeInstanceOf(CloudWebSearchValidationError);
+    });
+
+    it("maps persisted backend events into typed rich product events", async () => {
+        const raw = vi.fn().mockResolvedValue(new Response(toReadableStream(toSSEPayload([
+            {
+                event: "job.snapshot",
+                data: {
+                    job: createJob({
+                        mode: "research",
+                        searchQuery: null,
+                        searchInstructions: "Research browser-use alternatives",
+                        status: "in_progress",
+                    }),
+                },
+            },
+            {
+                event: "websearch.search.started",
+                data: createJobEvent({
+                    id: "evt_search_started",
+                    eventType: "websearch.search.started",
+                    stage: "search",
+                    status: "in_progress",
+                    message: "Executing web search",
+                    payload: { query: "browser-use alternatives" },
+                    createdAt: "2026-04-22T10:00:01.000Z",
+                }),
+            },
+            {
+                event: "websearch.search.completed",
+                data: createJobEvent({
+                    id: "evt_search_completed",
+                    eventType: "websearch.search.completed",
+                    stage: "search",
+                    status: "completed",
+                    message: "Web search completed",
+                    payload: {
+                        query: "browser-use alternatives",
+                        provider: "mock",
+                        results: [
+                            {
+                                title: "Source",
+                                url: "https://example.com/source",
+                                host: "example.com",
+                                snippet: "snippet",
+                                relevantContent: "extracted relevant text",
+                                keyFacts: ["fact"],
+                                confidence: 0.9,
+                                faviconUrl: "https://example.com/favicon.ico",
+                            },
+                        ],
+                    },
+                    createdAt: "2026-04-22T10:00:02.000Z",
+                }),
+            },
+            {
+                event: "websearch.source.opening",
+                data: createJobEvent({
+                    id: "evt_source_opening",
+                    eventType: "websearch.source.opening",
+                    stage: "fetch",
+                    status: "in_progress",
+                    message: "Opening source",
+                    payload: {
+                        index: 0,
+                        source: {
+                            title: "Source",
+                            url: "https://example.com/source",
+                            host: "example.com",
+                            faviconUrl: "https://example.com/favicon.ico",
+                        },
+                    },
+                    createdAt: "2026-04-22T10:00:02.250Z",
+                }),
+            },
+            {
+                event: "websearch.source.extracted",
+                data: createJobEvent({
+                    id: "evt_source_extracted",
+                    eventType: "websearch.source.extracted",
+                    stage: "extract",
+                    status: "completed",
+                    message: "Source extracted",
+                    payload: {
+                        index: 0,
+                        snippet: "extracted relevant text",
+                        confidence: 0.9,
+                        source: {
+                            title: "Source",
+                            url: "https://example.com/source",
+                            host: "example.com",
+                            relevantContent: "extracted relevant text",
+                            keyFacts: ["fact"],
+                            confidence: 0.9,
+                            faviconUrl: "https://example.com/favicon.ico",
+                        },
+                    },
+                    createdAt: "2026-04-22T10:00:02.500Z",
+                }),
+            },
+            {
+                event: "websearch.tool.sources.reviewing",
+                data: createJobEvent({
+                    id: "evt_sources_reviewing",
+                    eventType: "websearch.tool.sources.reviewing",
+                    stage: "review",
+                    status: "in_progress",
+                    message: "Reviewing extracted sources",
+                    payload: {
+                        totalExtractions: 1,
+                    },
+                    createdAt: "2026-04-22T10:00:02.600Z",
+                }),
+            },
+            {
+                event: "websearch.tool.sources.filtered",
+                data: createJobEvent({
+                    id: "evt_sources_filtered",
+                    eventType: "websearch.tool.sources.filtered",
+                    stage: "review",
+                    status: "in_progress",
+                    message: "Cross-checking extracted sources",
+                    payload: {
+                        totalSources: 1,
+                        credibleSources: 1,
+                        filteredOut: 0,
+                    },
+                    createdAt: "2026-04-22T10:00:02.700Z",
+                }),
+            },
+            {
+                event: "websearch.tool.retrieval.completed",
+                data: createJobEvent({
+                    id: "evt_sources_reviewed",
+                    eventType: "websearch.tool.retrieval.completed",
+                    stage: "review",
+                    status: "completed",
+                    message: "Source retrieval completed",
+                    payload: {
+                        credibleSourceCount: 1,
+                        sources: [{
+                            title: "Source",
+                            url: "https://example.com/source",
+                            host: "example.com",
+                            relevantContent: "extracted relevant text",
+                            keyFacts: ["fact"],
+                            confidence: 0.9,
+                            faviconUrl: "https://example.com/favicon.ico",
+                        }],
+                    },
+                    createdAt: "2026-04-22T10:00:02.800Z",
+                }),
+            },
+            {
+                event: "websearch.research.synthesis.started",
+                data: createJobEvent({
+                    id: "evt_synthesis_started",
+                    eventType: "websearch.research.synthesis.started",
+                    stage: "synthesize",
+                    status: "in_progress",
+                    message: "Synthesizing final answer",
+                    payload: null,
+                    createdAt: "2026-04-22T10:00:02.900Z",
+                }),
+            },
+            {
+                event: "websearch.research.answer.delta",
+                data: createJobEvent({
+                    id: "evt_delta",
+                    eventType: "websearch.research.answer.delta",
+                    stage: "research",
+                    status: "in_progress",
+                    message: "Streaming answer delta",
+                    payload: { delta: "partial" },
+                    createdAt: "2026-04-22T10:00:03.000Z",
+                }),
+            },
+            {
+                event: "websearch.research.synthesis.completed",
+                data: createJobEvent({
+                    id: "evt_synthesis_completed",
+                    eventType: "websearch.research.synthesis.completed",
+                    stage: "synthesize",
+                    status: "completed",
+                    message: "Final research synthesis completed",
+                    payload: {
+                        hasStructuredOutput: true,
+                        toolCalls: 1,
+                    },
+                    createdAt: "2026-04-22T10:00:03.500Z",
+                }),
+            },
+            {
+                event: "job.completed",
+                data: createJobEvent({
+                    id: "evt_completed",
+                    eventType: "job.completed",
+                    stage: "completed",
+                    status: "completed",
+                    message: "Web-search job completed",
+                    payload: {
+                        result: {
+                            output: { summary: "Ready", markdown: "# Ready\n\nDone [c1]" },
+                            text: "Ready",
+                            sources: [{
+                                title: "Source",
+                                url: "https://example.com/source",
+                                host: "example.com",
+                                relevantContent: "extracted relevant text",
+                                keyFacts: ["fact"],
+                                confidence: 0.9,
+                                faviconUrl: "https://example.com/favicon.ico",
+                            }],
+                        },
+                    },
+                    createdAt: "2026-04-22T10:00:04.000Z",
+                }),
+            },
+        ]))));
+        const transport = {
+            baseUrl: "https://api.kognitive.dev",
+            json: vi.fn(),
+            raw,
+            poll: vi.fn(),
+        } as unknown as HttpTransport;
+
+        const client = new KognitiveCloudWebSearchClient(transport);
+        const stream = await client.jobs.subscribeRich("job_123", {
+            parseOutput: parseSummary,
+        });
+        const events = await collect(stream);
+        const terminalEventTypes = events.slice(-2).map((event) => event.type);
+
+        expect(events).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                type: "search.started",
+                query: "browser-use alternatives",
+            }),
+            expect.objectContaining({
+                type: "search.completed",
+                provider: "mock",
+                results: [
+                    expect.objectContaining({
+                        title: "Source",
+                        host: "example.com",
+                        relevantContent: "extracted relevant text",
+                        keyFacts: ["fact"],
+                        confidence: 0.9,
+                        faviconUrl: "https://example.com/favicon.ico",
+                    }),
+                ],
+            }),
+            expect.objectContaining({
+                type: "source.opening",
+                index: 0,
+                source: expect.objectContaining({
+                    host: "example.com",
+                    faviconUrl: "https://example.com/favicon.ico",
+                }),
+            }),
+            expect.objectContaining({
+                type: "source.extracted",
+                index: 0,
+                snippet: "extracted relevant text",
+                confidence: 0.9,
+                source: expect.objectContaining({
+                    relevantContent: "extracted relevant text",
+                    keyFacts: ["fact"],
+                }),
+            }),
+            expect.objectContaining({
+                type: "sources.reviewing",
+                totalExtractions: 1,
+            }),
+            expect.objectContaining({
+                type: "sources.filtered",
+                totalSources: 1,
+                credibleSources: 1,
+                filteredOut: 0,
+            }),
+            expect.objectContaining({
+                type: "sources.reviewed",
+                credibleSourceCount: 1,
+                sources: [
+                    expect.objectContaining({
+                        host: "example.com",
+                        relevantContent: "extracted relevant text",
+                    }),
+                ],
+            }),
+            expect.objectContaining({
+                type: "synthesis.started",
+            }),
+            expect.objectContaining({
+                type: "answer.delta",
+                delta: "partial",
+            }),
+            expect.objectContaining({
+                type: "synthesis.completed",
+            }),
+            expect.objectContaining({
+                type: "completed",
+                result: {
+                    output: { summary: "Ready", markdown: "# Ready\n\nDone [c1]" },
+                    text: "Ready",
+                    sources: [
+                        expect.objectContaining({
+                            host: "example.com",
+                            relevantContent: "extracted relevant text",
+                        }),
+                    ],
+                },
+            }),
+            expect.objectContaining({
+                type: "answer.completed",
+                answer: { summary: "Ready", markdown: "# Ready\n\nDone [c1]" },
+            }),
+        ]));
+        expect(terminalEventTypes).toEqual(["answer.completed", "completed"]);
+
+        expect(toCloudWebSearchRichEvents({
+            type: "unknown",
+            job: null,
+            frame: { event: "opaque", data: {} },
+        })).toEqual([]);
+    });
+});