@kognitivedev/cloud-web-search 0.2.28

package/src/index.ts

@@ -0,0 +1,33 @@
+export { KognitiveCloudWebSearchClient, readCloudWebSearchEventStream } from "./client";
+export { CloudWebSearchStreamProtocolError, CloudWebSearchValidationError } from "./errors";
+export { toCloudWebSearchRichEvents } from "./rich-events";
+export { readSSEStream } from "./sse";
+export type { ParsedSSEEvent } from "./sse";
+export type {
+    CloudWebSearchClientConfig,
+    CloudWebSearchDecodeOptions,
+    CloudWebSearchExecutionParameters,
+    CloudWebSearchJobEventRecord,
+    CloudWebSearchJobRecord,
+    CloudWebSearchJobResultEnvelope,
+    CloudWebSearchJobStatus,
+    CloudWebSearchJobWaitResult,
+    CloudWebSearchMode,
+    CloudWebSearchOutputParser,
+    CloudWebSearchProductAnswer,
+    CloudWebSearchProgressEntry,
+    CloudWebSearchRichEvent,
+    CloudWebSearchRichSource,
+    CloudWebSearchResearchJobInput,
+    CloudWebSearchResult,
+    CloudWebSearchSearchJobInput,
+    CloudWebSearchSource,
+    CloudWebSearchStreamEvent,
+    CloudWebSearchSubscribeOptions,
+    CloudWebSearchTimeRange,
+    CreateCloudWebSearchJobInput,
+    LogLevel,
+    ResearchPlan,
+    ResearchPlanTodo,
+    WaitForCompletionOptions,
+} from "./types";

package/src/rich-events.ts

@@ -0,0 +1,256 @@
+import type {
+    CloudWebSearchJobEventRecord,
+    CloudWebSearchProductAnswer,
+    CloudWebSearchRichEvent,
+    CloudWebSearchRichSource,
+    CloudWebSearchStreamEvent,
+} from "./types";
+import { cloneUnknown, isPlainObject } from "./validation";
+
+function asString(value: unknown): string | null {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+
+function asNumber(value: unknown): number | null {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function asIndex(value: unknown): number | null {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function toSource(value: unknown): CloudWebSearchRichSource | null {
+    if (!isPlainObject(value)) return null;
+    const url = asString(value.url);
+    const title = asString(value.title);
+    const keyFacts = Array.isArray(value.keyFacts)
+        ? value.keyFacts.filter((fact): fact is string => typeof fact === "string")
+        : undefined;
+
+    return {
+        title,
+        url,
+        snippet: asString(value.snippet),
+        score: asNumber(value.score),
+        confidence: asNumber(value.confidence),
+        faviconUrl: asString(value.faviconUrl),
+        host: asString(value.host),
+        relevantContent: asString(value.relevantContent),
+        ...(keyFacts ? { keyFacts } : {}),
+    };
+}
+
+function sourceFromPayload(payload: Record<string, unknown>): CloudWebSearchRichSource | null {
+    if (isPlainObject(payload.source)) {
+        return toSource(payload.source);
+    }
+    return toSource(payload);
+}
+
+function sourcesFromPayload(payload: Record<string, unknown>): CloudWebSearchRichSource[] {
+    const values = Array.isArray(payload.results)
+        ? payload.results
+        : Array.isArray(payload.sources)
+            ? payload.sources
+            : [];
+    return values.map((source) => toSource(source)).filter((source): source is CloudWebSearchRichSource => Boolean(source));
+}
+
+function payloadOf(record: CloudWebSearchJobEventRecord): Record<string, unknown> {
+    return isPlainObject(record.payload) ? record.payload : {};
+}
+
+function answerFromResult(value: unknown): CloudWebSearchProductAnswer | null {
+    if (!isPlainObject(value)) return null;
+    if (isPlainObject(value.output)) {
+        return cloneUnknown(value.output) as CloudWebSearchProductAnswer;
+    }
+    return null;
+}
+
+function fromRecord<TOutput>(
+    record: CloudWebSearchJobEventRecord,
+): CloudWebSearchRichEvent<TOutput>[] {
+    const payload = payloadOf(record);
+    const base = {
+        jobId: record.jobId,
+        eventId: record.id,
+        raw: cloneUnknown(record),
+    };
+
+    switch (record.eventType) {
+        case "websearch.research.plan.started":
+            return [{
+                type: "plan.started",
+                ...base,
+                message: record.message,
+            }];
+        case "websearch.research.plan.completed":
+            return [{
+                type: "plan.completed",
+                ...base,
+                plan: isPlainObject(record.payload) ? cloneUnknown(record.payload as any) : null,
+            }];
+        case "websearch.research.todo.generated":
+            return [{
+                type: "todo.generated",
+                ...base,
+                todo: isPlainObject(record.payload) ? cloneUnknown(record.payload as any) : null,
+            }];
+        case "websearch.search.started":
+            return [{
+                type: "search.started",
+                ...base,
+                query: asString(payload.query),
+                input: payload.input,
+            }];
+        case "websearch.search.completed":
+            return [{
+                type: "search.completed",
+                ...base,
+                query: asString(payload.query),
+                provider: asString(payload.provider),
+                results: sourcesFromPayload(payload),
+            }];
+        case "websearch.fetch.started":
+        case "websearch.source.opening":
+            return [{
+                type: "source.opening",
+                ...base,
+                source: sourceFromPayload(payload),
+                index: asIndex(payload.index),
+            }];
+        case "websearch.extract.completed":
+        case "websearch.source.extracted":
+            return [{
+                type: "source.extracted",
+                ...base,
+                source: sourceFromPayload(payload),
+                snippet: asString(payload.snippet),
+                confidence: asNumber(payload.confidence),
+                index: asIndex(payload.index),
+            }];
+        case "websearch.fetch.failed":
+        case "websearch.source.failed":
+            return [{
+                type: "source.failed",
+                ...base,
+                source: sourceFromPayload(payload),
+                errorMessage: asString(payload.error) ?? asString(payload.errorMessage),
+                index: asIndex(payload.index),
+            }];
+        case "websearch.research.reasoning":
+            return asString(payload.delta)
+                ? [{
+                    type: "reasoning.delta",
+                    ...base,
+                    delta: asString(payload.delta)!,
+                }]
+                : [];
+        case "websearch.research.answer.delta":
+            return asString(payload.delta)
+                ? [{
+                    type: "answer.delta",
+                    ...base,
+                    delta: asString(payload.delta)!,
+                }]
+                : [];
+        case "websearch.tool.sources.reviewing":
+        case "websearch.tool.synthesis.started":
+            return [{
+                type: "sources.reviewing",
+                ...base,
+                totalExtractions: asNumber(payload.totalExtractions),
+                message: record.message,
+            }];
+        case "websearch.tool.sources.filtered":
+            return [{
+                type: "sources.filtered",
+                ...base,
+                totalSources: asNumber(payload.totalSources),
+                credibleSources: asNumber(payload.credibleSources),
+                filteredOut: asNumber(payload.filteredOut),
+                message: record.message,
+            }];
+        case "websearch.tool.retrieval.completed":
+        case "websearch.tool.synthesis.completed":
+            return [{
+                type: "sources.reviewed",
+                ...base,
+                sources: sourcesFromPayload(payload),
+                credibleSourceCount: asNumber(payload.credibleSourceCount),
+            }];
+        case "websearch.research.synthesis.started":
+        case "websearch.synthesis.started":
+            return [{
+                type: "synthesis.started",
+                ...base,
+                totalExtractions: asNumber(payload.totalExtractions),
+            }];
+        case "websearch.research.synthesis.completed":
+            return [{
+                type: "synthesis.completed",
+                ...base,
+            }];
+        case "websearch.research.answer.completed":
+            return [{
+                type: "answer.completed",
+                ...base,
+            }];
+        default:
+            return [];
+    }
+}
+
+export function toCloudWebSearchRichEvents<TOutput = unknown>(
+    event: CloudWebSearchStreamEvent<TOutput>,
+): CloudWebSearchRichEvent<TOutput>[] {
+    if (event.type === "progress" && event.raw) {
+        return fromRecord<TOutput>(event.raw);
+    }
+
+    if (event.type === "event") {
+        return fromRecord<TOutput>(event.event);
+    }
+
+    if (event.type === "completed") {
+        return [{
+            type: "answer.completed",
+            jobId: event.jobId,
+            result: event.result,
+            answer: answerFromResult(event.result),
+            ...(event.eventId ? { eventId: event.eventId } : {}),
+            ...(event.raw ? { raw: event.raw } : {}),
+        }, {
+            type: "completed",
+            jobId: event.jobId,
+            job: event.job,
+            result: event.result,
+            ...(event.eventId ? { eventId: event.eventId } : {}),
+            ...(event.raw ? { raw: event.raw } : {}),
+        }];
+    }
+
+    if (event.type === "error") {
+        return [{
+            type: "error",
+            jobId: event.jobId,
+            job: event.job,
+            errorMessage: event.errorMessage,
+            ...(event.eventId ? { eventId: event.eventId } : {}),
+            ...(event.raw ? { raw: event.raw } : {}),
+        }];
+    }
+
+    if (event.type === "cancelled") {
+        return [{
+            type: "cancelled",
+            jobId: event.jobId,
+            job: event.job,
+            ...(event.eventId ? { eventId: event.eventId } : {}),
+            ...(event.raw ? { raw: event.raw } : {}),
+        }];
+    }
+
+    return [];
+}

package/src/sse.ts

@@ -0,0 +1,173 @@
+export type ParsedSSEEvent<T = unknown> = {
+    event: string;
+    data: T;
+    dataText: string;
+    id?: string;
+    retry?: number;
+};
+
+function parseEventData<T>(dataText: string): T {
+    try {
+        return JSON.parse(dataText) as T;
+    } catch {
+        return dataText as T;
+    }
+}
+
+function finalizeEvent<T>(
+    eventName: string,
+    dataLines: string[],
+    lastEventId: string | undefined,
+    retry: number | undefined,
+): ParsedSSEEvent<T> | null {
+    if (dataLines.length === 0) {
+        return null;
+    }
+
+    const dataText = dataLines.join("\n");
+    return {
+        event: eventName || "message",
+        data: parseEventData<T>(dataText),
+        dataText,
+        ...(lastEventId === undefined ? {} : { id: lastEventId }),
+        ...(retry === undefined ? {} : { retry }),
+    };
+}
+
+function findNextLineBreak(buffer: string): { index: number; length: number } | null {
+    for (let index = 0; index < buffer.length; index += 1) {
+        const code = buffer.charCodeAt(index);
+        if (code === 0x0a) {
+            return { index, length: 1 };
+        }
+        if (code === 0x0d) {
+            return {
+                index,
+                length: buffer.charCodeAt(index + 1) === 0x0a ? 2 : 1,
+            };
+        }
+    }
+
+    return null;
+}
+
+function parseField(line: string): { field: string; value: string } {
+    const separator = line.indexOf(":");
+    if (separator < 0) {
+        return { field: line, value: "" };
+    }
+
+    let value = line.slice(separator + 1);
+    if (value.startsWith(" ")) {
+        value = value.slice(1);
+    }
+
+    return {
+        field: line.slice(0, separator),
+        value,
+    };
+}
+
+export async function* readSSEStream<T = unknown>(
+    stream: ReadableStream<Uint8Array>,
+): AsyncGenerator<ParsedSSEEvent<T>> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+
+    let buffer = "";
+    let eventName = "message";
+    let dataLines: string[] = [];
+    let lastEventId: string | undefined;
+    let pendingEventId: string | undefined;
+    let pendingRetry: number | undefined;
+
+    const processLine = (line: string): ParsedSSEEvent<T> | null => {
+        if (line === "") {
+            if (pendingEventId !== undefined) {
+                lastEventId = pendingEventId;
+            }
+
+            const event = finalizeEvent<T>(eventName, dataLines, lastEventId, pendingRetry);
+            eventName = "message";
+            dataLines = [];
+            pendingEventId = undefined;
+            pendingRetry = undefined;
+            return event;
+        }
+
+        if (line.startsWith(":")) {
+            return null;
+        }
+
+        const { field, value } = parseField(line);
+        switch (field) {
+            case "event":
+                eventName = value || "message";
+                break;
+            case "data":
+                dataLines.push(value);
+                break;
+            case "id":
+                if (!value.includes("\0")) {
+                    pendingEventId = value;
+                }
+                break;
+            case "retry":
+                if (/^\d+$/.test(value)) {
+                    pendingRetry = Number.parseInt(value, 10);
+                }
+                break;
+            default:
+                break;
+        }
+
+        return null;
+    };
+
+    try {
+        let isDone = false;
+
+        while (!isDone) {
+            const { done, value } = await reader.read();
+            isDone = done;
+            buffer += decoder.decode(value ?? new Uint8Array(), { stream: !done });
+
+            let nextLine = findNextLineBreak(buffer);
+            while (nextLine) {
+                const line = buffer.slice(0, nextLine.index);
+                buffer = buffer.slice(nextLine.index + nextLine.length);
+
+                const event = processLine(line);
+                if (event) {
+                    yield event;
+                }
+
+                nextLine = findNextLineBreak(buffer);
+            }
+        }
+
+        buffer += decoder.decode();
+        if (buffer.length > 0) {
+            const event = processLine(buffer);
+            if (event) {
+                yield event;
+            }
+        }
+
+        if (pendingEventId !== undefined) {
+            lastEventId = pendingEventId;
+        }
+
+        const trailingEvent = finalizeEvent<T>(eventName, dataLines, lastEventId, pendingRetry);
+        if (trailingEvent) {
+            yield trailingEvent;
+        }
+    } finally {
+        try {
+            await reader.cancel();
+        } catch {
+            // Best effort cleanup for partially consumed streams.
+        }
+        reader.releaseLock();
+    }
+}