@kognitivedev/cloud-web-search 0.2.28

package/src/client.ts

@@ -0,0 +1,664 @@
+import { HttpTransport, type HttpTransportConfig } from "@kognitivedev/client-core";
+import { CloudWebSearchStreamProtocolError, CloudWebSearchValidationError } from "./errors";
+import { toCloudWebSearchRichEvents } from "./rich-events";
+import { readSSEStream } from "./sse";
+import type {
+    CloudWebSearchClientConfig,
+    CloudWebSearchDecodeOptions,
+    CloudWebSearchExecutionParameters,
+    CloudWebSearchJobEventRecord,
+    CloudWebSearchJobRecord,
+    CloudWebSearchJobResultEnvelope,
+    CloudWebSearchJobStatus,
+    CloudWebSearchJobWaitResult,
+    CloudWebSearchProgressEntry,
+    CloudWebSearchResearchJobInput,
+    CloudWebSearchResult,
+    CloudWebSearchRichEvent,
+    CloudWebSearchSearchJobInput,
+    CloudWebSearchStreamEvent,
+    CloudWebSearchSubscribeOptions,
+    CreateCloudWebSearchJobInput,
+    WaitForCompletionOptions,
+} from "./types";
+import {
+    cloneUnknown,
+    decodeCloudWebSearchJobEventRecord,
+    decodeCloudWebSearchJobListEnvelope,
+    decodeCloudWebSearchJobRecord,
+    decodeCloudWebSearchJobResultEnvelope,
+    decodeCloudWebSearchResult,
+    decodeDirectCancelledPayload,
+    decodeDirectCompletedPayload,
+    decodeDirectErrorPayload,
+    decodeDirectProgressPayload,
+    decodeJobSnapshotPayload,
+    decodeKeepalivePayload,
+    isJobStatus,
+    isPlainObject,
+    validateCreateCloudWebSearchJobInput,
+} from "./validation";
+
+const TERMINAL_STATUSES = new Set<CloudWebSearchJobStatus>(["completed", "error", "cancelled"]);
+
+const NON_PROGRESS_EVENT_TYPES = new Set([
+    "job.completed",
+    "job.failed",
+    "job.error",
+    "job.cancelled",
+    "websearch.research.answer.delta",
+    "websearch.research.reasoning",
+    "websearch.research.status",
+    "websearch.research.todo.generated",
+    "websearch.research.answer.completed",
+]);
+
+function isTransportLike(value: unknown): value is HttpTransport {
+    return Boolean(
+        value
+        && typeof value === "object"
+        && "baseUrl" in value
+        && "json" in value
+        && "raw" in value
+        && "poll" in value,
+    );
+}
+
+function stableStringify(value: unknown): string {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+    }
+    if (value instanceof Date) {
+        return JSON.stringify(value.toISOString());
+    }
+    if (isPlainObject(value)) {
+        return `{${Object.keys(value).sort().map((key) =>
+            `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+
+function toProgressFingerprint(progress: CloudWebSearchProgressEntry): string {
+    return stableStringify({
+        stage: progress.stage,
+        message: progress.message,
+        timestamp: progress.timestamp,
+    });
+}
+
+function rememberProgress(
+    seenProgress: Set<string>,
+    progress: CloudWebSearchProgressEntry,
+    eventId?: string,
+): boolean {
+    const progressKey = `progress:${toProgressFingerprint(progress)}`;
+    const eventKey = eventId ? `event:${eventId}` : null;
+    const duplicate = seenProgress.has(progressKey) || (eventKey ? seenProgress.has(eventKey) : false);
+
+    seenProgress.add(progressKey);
+    if (eventKey) {
+        seenProgress.add(eventKey);
+    }
+
+    return !duplicate;
+}
+
+function normalizeTimestamp(value: string | Date): string {
+    return typeof value === "string" ? value : value.toISOString();
+}
+
+function deriveStatusFromRecord(record: CloudWebSearchJobEventRecord, fallback?: CloudWebSearchJobStatus): CloudWebSearchJobStatus {
+    if (isJobStatus(record.status)) {
+        return record.status;
+    }
+
+    switch (record.eventType) {
+        case "job.created":
+            return "queued";
+        case "job.started":
+            return "in_progress";
+        case "job.completed":
+            return "completed";
+        case "job.failed":
+        case "job.error":
+            return "error";
+        case "job.cancelled":
+            return "cancelled";
+        default:
+            return fallback ?? "in_progress";
+    }
+}
+
+function toProgressEntry(record: CloudWebSearchJobEventRecord): CloudWebSearchProgressEntry | null {
+    if (typeof record.stage !== "string" || typeof record.message !== "string") {
+        return null;
+    }
+
+    const payload = isPlainObject(record.payload) ? cloneUnknown(record.payload) : undefined;
+    return {
+        stage: record.stage,
+        message: record.message,
+        timestamp: normalizeTimestamp(record.createdAt),
+        ...(payload ? { metadata: payload } : {}),
+    };
+}
+
+function shouldEmitProgress(record: CloudWebSearchJobEventRecord): boolean {
+    if (typeof record.stage !== "string" || typeof record.message !== "string") {
+        return false;
+    }
+    if (NON_PROGRESS_EVENT_TYPES.has(record.eventType)) {
+        return false;
+    }
+    if (record.eventType.startsWith("websearch.workflow.")) {
+        return false;
+    }
+    return true;
+}
+
+function assertJobId(jobId: string, path = "jobId"): string {
+    const value = jobId.trim();
+    if (!value) {
+        throw new CloudWebSearchValidationError(path, "non-empty string", jobId);
+    }
+    return value;
+}
+
+function rememberObservedJobId(observedJobId: string | null, nextJobId: string, path: string): string {
+    if (observedJobId && observedJobId !== nextJobId) {
+        throw new CloudWebSearchValidationError(path, `jobId "${observedJobId}"`, nextJobId);
+    }
+    return nextJobId;
+}
+
+function extractResultFromPayload<TOutput = unknown>(
+    payload: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "event.payload",
+): CloudWebSearchResult<TOutput> | null {
+    if (payload === undefined || payload === null) {
+        return null;
+    }
+    if (isPlainObject(payload) && "result" in payload) {
+        return payload.result === null
+            ? null
+            : decodeCloudWebSearchResult(payload.result, options, `${path}.result`);
+    }
+    return decodeCloudWebSearchResult(payload, options, path);
+}
+
+function extractErrorMessage(payload: unknown, fallback: string): string {
+    if (isPlainObject(payload) && typeof payload.errorMessage === "string" && payload.errorMessage.trim()) {
+        return payload.errorMessage;
+    }
+    if (isPlainObject(payload) && typeof payload.reason === "string" && payload.reason.trim()) {
+        return payload.reason;
+    }
+    return fallback;
+}
+
+function applyLifecycleUpdate<TOutput = unknown>(
+    job: CloudWebSearchJobRecord<TOutput> | null,
+    record: CloudWebSearchJobEventRecord,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+) {
+    if (!job) {
+        return;
+    }
+
+    job.updatedAt = normalizeTimestamp(record.createdAt);
+
+    switch (record.eventType) {
+        case "job.created":
+            job.status = "queued";
+            break;
+        case "job.started":
+            job.status = "in_progress";
+            break;
+        case "job.completed":
+            job.status = "completed";
+            job.results = extractResultFromPayload(record.payload, options, `stream.${record.eventType}.payload`);
+            job.errorMessage = null;
+            break;
+        case "job.failed":
+        case "job.error":
+            job.status = "error";
+            job.errorMessage = extractErrorMessage(record.payload, record.message ?? "Web search job failed");
+            break;
+        case "job.cancelled":
+            job.status = "cancelled";
+            job.errorMessage = "Job cancelled";
+            break;
+        default:
+            break;
+    }
+}
+
+function createSearchJobInput(
+    input: Omit<CloudWebSearchSearchJobInput, "mode"> | string,
+    parameters?: CloudWebSearchExecutionParameters,
+): CloudWebSearchSearchJobInput {
+    if (typeof input === "string") {
+        return {
+            mode: "search",
+            query: input,
+            ...(parameters ? { parameters } : {}),
+        };
+    }
+
+    return {
+        mode: "search",
+        query: input.query,
+        ...(input.parameters ? { parameters: input.parameters } : {}),
+    };
+}
+
+function createResearchJobInput(
+    input: Omit<CloudWebSearchResearchJobInput, "mode"> | string,
+    options?: Omit<CloudWebSearchResearchJobInput, "mode" | "instructions">,
+): CloudWebSearchResearchJobInput {
+    if (typeof input === "string") {
+        return {
+            mode: "research",
+            instructions: input,
+            ...(options?.responseInstructions ? { responseInstructions: options.responseInstructions } : {}),
+            ...(options?.responseSchema ? { responseSchema: options.responseSchema } : {}),
+            ...(options?.parameters ? { parameters: options.parameters } : {}),
+        };
+    }
+
+    return {
+        mode: "research",
+        instructions: input.instructions,
+        ...(input.responseInstructions ? { responseInstructions: input.responseInstructions } : {}),
+        ...(input.responseSchema ? { responseSchema: input.responseSchema } : {}),
+        ...(input.parameters ? { parameters: input.parameters } : {}),
+    };
+}
+
+export async function* readCloudWebSearchEventStream<TOutput = unknown>(
+    stream: ReadableStream<Uint8Array>,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+): AsyncGenerator<CloudWebSearchStreamEvent<TOutput>> {
+    let currentJob: CloudWebSearchJobRecord<TOutput> | null = null;
+    let observedJobId: string | null = null;
+    const seenProgress = new Set<string>();
+
+    for await (const frame of readSSEStream(stream)) {
+        let lifecycleDecodeError: CloudWebSearchValidationError | null = null;
+
+        if (frame.event === "job.snapshot") {
+            const payload = decodeJobSnapshotPayload(frame.data, options, "stream.job.snapshot");
+            observedJobId = rememberObservedJobId(observedJobId, payload.job.id, "stream.job.snapshot.job.id");
+            currentJob = cloneUnknown(payload.job);
+
+            yield {
+                type: "snapshot",
+                job: cloneUnknown(currentJob),
+            };
+
+            for (const progress of currentJob.progress) {
+                if (!rememberProgress(seenProgress, progress)) {
+                    continue;
+                }
+                yield {
+                    type: "progress",
+                    jobId: currentJob.id,
+                    job: cloneUnknown(currentJob),
+                    status: currentJob.status,
+                    progress: cloneUnknown(progress),
+                    replay: true,
+                };
+            }
+            continue;
+        }
+
+        if (frame.event === "job.keepalive") {
+            const payload = decodeKeepalivePayload(frame.data, "stream.job.keepalive");
+            observedJobId = rememberObservedJobId(observedJobId, payload.jobId, "stream.job.keepalive.jobId");
+            yield {
+                type: "keepalive",
+                jobId: payload.jobId,
+                timestamp: payload.timestamp,
+            };
+            continue;
+        }
+
+        if (frame.event === "job.progress") {
+            try {
+                const payload = decodeDirectProgressPayload(frame.data, "stream.job.progress");
+                observedJobId = rememberObservedJobId(observedJobId, payload.jobId, "stream.job.progress.jobId");
+
+                if (!rememberProgress(seenProgress, payload.progress, frame.id)) {
+                    continue;
+                }
+
+                if (currentJob && currentJob.id === payload.jobId) {
+                    currentJob.status = payload.status;
+                    currentJob.progress.push(cloneUnknown(payload.progress));
+                    currentJob.updatedAt = payload.progress.timestamp;
+                }
+
+                yield {
+                    type: "progress",
+                    jobId: payload.jobId,
+                    job: cloneUnknown(currentJob),
+                    status: payload.status,
+                    progress: cloneUnknown(payload.progress),
+                    ...(frame.id ? { eventId: frame.id } : {}),
+                };
+                continue;
+            } catch (error) {
+                if (!(error instanceof CloudWebSearchValidationError)) {
+                    throw error;
+                }
+                lifecycleDecodeError = error;
+            }
+        }
+
+        if (frame.event === "job.completed") {
+            try {
+                const payload = decodeDirectCompletedPayload(frame.data, options, "stream.job.completed");
+                observedJobId = rememberObservedJobId(observedJobId, payload.job.id, "stream.job.completed.job.id");
+                currentJob = cloneUnknown(payload.job);
+                currentJob.status = "completed";
+                currentJob.results = cloneUnknown(payload.result);
+
+                yield {
+                    type: "completed",
+                    jobId: payload.job.id,
+                    job: cloneUnknown(currentJob),
+                    result: cloneUnknown(payload.result),
+                    ...(frame.id ? { eventId: frame.id } : {}),
+                };
+                continue;
+            } catch (error) {
+                if (!(error instanceof CloudWebSearchValidationError)) {
+                    throw error;
+                }
+                lifecycleDecodeError = error;
+            }
+        }
+
+        if (frame.event === "job.error" || frame.event === "job.failed") {
+            try {
+                const payload = decodeDirectErrorPayload(frame.data, options, `stream.${frame.event}`);
+                observedJobId = rememberObservedJobId(observedJobId, payload.job.id, `stream.${frame.event}.job.id`);
+                currentJob = cloneUnknown(payload.job);
+                currentJob.status = "error";
+                currentJob.errorMessage = payload.errorMessage;
+
+                yield {
+                    type: "error",
+                    jobId: payload.job.id,
+                    job: cloneUnknown(currentJob),
+                    errorMessage: payload.errorMessage,
+                    ...(frame.id ? { eventId: frame.id } : {}),
+                };
+                continue;
+            } catch (error) {
+                if (!(error instanceof CloudWebSearchValidationError)) {
+                    throw error;
+                }
+                lifecycleDecodeError = error;
+            }
+        }
+
+        if (frame.event === "job.cancelled") {
+            try {
+                const payload = decodeDirectCancelledPayload(frame.data, options, "stream.job.cancelled");
+                observedJobId = rememberObservedJobId(observedJobId, payload.job.id, "stream.job.cancelled.job.id");
+                currentJob = cloneUnknown(payload.job);
+                currentJob.status = "cancelled";
+                currentJob.errorMessage = currentJob.errorMessage ?? "Job cancelled";
+
+                yield {
+                    type: "cancelled",
+                    jobId: payload.job.id,
+                    job: cloneUnknown(currentJob),
+                    ...(frame.id ? { eventId: frame.id } : {}),
+                };
+                continue;
+            } catch (error) {
+                if (!(error instanceof CloudWebSearchValidationError)) {
+                    throw error;
+                }
+                lifecycleDecodeError = error;
+            }
+        }
+
+        let record: CloudWebSearchJobEventRecord | null = null;
+        try {
+            record = decodeCloudWebSearchJobEventRecord(frame.data, `stream.${frame.event}`);
+        } catch (error) {
+            if (lifecycleDecodeError) {
+                throw lifecycleDecodeError;
+            }
+            if (error instanceof CloudWebSearchValidationError) {
+                yield {
+                    type: "unknown",
+                    job: cloneUnknown(currentJob),
+                    frame: cloneUnknown(frame),
+                };
+                continue;
+            }
+            throw error;
+        }
+
+        observedJobId = rememberObservedJobId(observedJobId, record.jobId, `stream.${frame.event}.jobId`);
+        applyLifecycleUpdate(currentJob, record, options);
+
+        if (shouldEmitProgress(record)) {
+            const progress = toProgressEntry(record);
+            if (progress && rememberProgress(seenProgress, progress, record.id)) {
+                if (currentJob && currentJob.id === record.jobId) {
+                    currentJob.status = deriveStatusFromRecord(record, currentJob.status);
+                    currentJob.progress.push(cloneUnknown(progress));
+                    currentJob.updatedAt = progress.timestamp;
+                }
+
+                yield {
+                    type: "progress",
+                    jobId: record.jobId,
+                    job: cloneUnknown(currentJob),
+                    status: deriveStatusFromRecord(record, currentJob?.status),
+                    progress: cloneUnknown(progress),
+                    eventId: record.id,
+                    rawEventType: record.eventType,
+                    raw: cloneUnknown(record),
+                };
+            }
+            continue;
+        }
+
+        if (record.eventType === "job.completed") {
+            yield {
+                type: "completed",
+                jobId: record.jobId,
+                job: cloneUnknown(currentJob),
+                result: cloneUnknown(currentJob?.results ?? extractResultFromPayload(record.payload, options, `stream.${record.eventType}.payload`)),
+                eventId: record.id,
+                raw: cloneUnknown(record),
+            };
+            continue;
+        }
+
+        if (record.eventType === "job.failed" || record.eventType === "job.error") {
+            yield {
+                type: "error",
+                jobId: record.jobId,
+                job: cloneUnknown(currentJob),
+                errorMessage: currentJob?.errorMessage ?? extractErrorMessage(record.payload, "Web search job failed"),
+                eventId: record.id,
+                raw: cloneUnknown(record),
+            };
+            continue;
+        }
+
+        if (record.eventType === "job.cancelled") {
+            yield {
+                type: "cancelled",
+                jobId: record.jobId,
+                job: cloneUnknown(currentJob),
+                eventId: record.id,
+                raw: cloneUnknown(record),
+            };
+            continue;
+        }
+
+        yield {
+            type: "event",
+            jobId: record.jobId,
+            job: cloneUnknown(currentJob),
+            event: cloneUnknown(record),
+        };
+    }
+}
+
+export class KognitiveCloudWebSearchClient {
+    private readonly transport: HttpTransport;
+
+    readonly jobs = {
+        list: <TOutput = unknown>(options?: CloudWebSearchDecodeOptions<TOutput>) => this.listJobs(options),
+        create: (input: CreateCloudWebSearchJobInput) => this.createJob(input),
+        createSearch: (input: Omit<CloudWebSearchSearchJobInput, "mode"> | string, parameters?: CloudWebSearchExecutionParameters) =>
+            this.createSearchJob(input, parameters),
+        createResearch: <TOutput = unknown>(
+            input: Omit<CloudWebSearchResearchJobInput, "mode"> | string,
+            options?: Omit<CloudWebSearchResearchJobInput, "mode" | "instructions">,
+        ) => this.createResearchJob<TOutput>(input, options),
+        get: <TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>) => this.getJob(jobId, options),
+        result: <TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>) => this.getJobResult(jobId, options),
+        cancel: <TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>) => this.cancelJob(jobId, options),
+        stream: (jobId: string, init?: RequestInit) => this.streamJob(jobId, init),
+        subscribe: <TOutput = unknown>(jobId: string, options?: CloudWebSearchSubscribeOptions<TOutput>) => this.subscribeToJob(jobId, options),
+        subscribeRich: <TOutput = unknown>(jobId: string, options?: CloudWebSearchSubscribeOptions<TOutput>) =>
+            this.subscribeToRichJob(jobId, options),
+        streamUrl: (jobId: string) => this.getJobEventsStreamUrl(jobId),
+        waitForCompletion: <TOutput = unknown>(jobId: string, options?: WaitForCompletionOptions<TOutput>) =>
+            this.waitForCompletion(jobId, options),
+    };
+
+    constructor(config: CloudWebSearchClientConfig | HttpTransport) {
+        this.transport = isTransportLike(config) ? config : new HttpTransport(config as HttpTransportConfig);
+    }
+
+    getJobEventsStreamUrl(jobId: string): string {
+        return `${this.transport.baseUrl}/api/cloud/web-search/jobs/${encodeURIComponent(assertJobId(jobId))}/events/stream`;
+    }
+
+    async listJobs<TOutput = unknown>(options?: CloudWebSearchDecodeOptions<TOutput>): Promise<CloudWebSearchJobRecord<TOutput>[]> {
+        const response = await this.transport.json<unknown>("/api/cloud/web-search/jobs");
+        return decodeCloudWebSearchJobListEnvelope(response, options).jobs;
+    }
+
+    async createJob(input: CreateCloudWebSearchJobInput): Promise<CloudWebSearchJobRecord> {
+        const body = validateCreateCloudWebSearchJobInput(input);
+        const response = await this.transport.json<unknown>("/api/cloud/web-search/jobs", {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+        return decodeCloudWebSearchJobRecord(response, undefined, "jobs.create");
+    }
+
+    async createSearchJob(
+        input: Omit<CloudWebSearchSearchJobInput, "mode"> | string,
+        parameters?: CloudWebSearchExecutionParameters,
+    ): Promise<CloudWebSearchJobRecord> {
+        return this.createJob(createSearchJobInput(input, parameters));
+    }
+
+    async createResearchJob<TOutput = unknown>(
+        input: Omit<CloudWebSearchResearchJobInput, "mode"> | string,
+        options?: Omit<CloudWebSearchResearchJobInput, "mode" | "instructions">,
+    ): Promise<CloudWebSearchJobRecord<TOutput>> {
+        return this.createJob(createResearchJobInput(input, options)) as Promise<CloudWebSearchJobRecord<TOutput>>;
+    }
+
+    async getJob<TOutput = unknown>(
+        jobId: string,
+        options?: CloudWebSearchDecodeOptions<TOutput>,
+    ): Promise<CloudWebSearchJobRecord<TOutput>> {
+        const response = await this.transport.json<unknown>(`/api/cloud/web-search/jobs/${encodeURIComponent(assertJobId(jobId))}`);
+        return decodeCloudWebSearchJobRecord(response, options, "jobs.get");
+    }
+
+    async getJobResult<TOutput = unknown>(
+        jobId: string,
+        options?: CloudWebSearchDecodeOptions<TOutput>,
+    ): Promise<CloudWebSearchJobResultEnvelope<TOutput>> {
+        const response = await this.transport.json<unknown>(`/api/cloud/web-search/jobs/${encodeURIComponent(assertJobId(jobId))}/result`);
+        return decodeCloudWebSearchJobResultEnvelope(response, options, "jobs.result");
+    }
+
+    async cancelJob<TOutput = unknown>(
+        jobId: string,
+        options?: CloudWebSearchDecodeOptions<TOutput>,
+    ): Promise<CloudWebSearchJobRecord<TOutput>> {
+        const response = await this.transport.json<unknown>(`/api/cloud/web-search/jobs/${encodeURIComponent(assertJobId(jobId))}/cancel`, {
+            method: "POST",
+        });
+        return decodeCloudWebSearchJobRecord(response, options, "jobs.cancel");
+    }
+
+    async streamJob(jobId: string, init?: RequestInit): Promise<Response> {
+        return this.transport.raw(`/api/cloud/web-search/jobs/${encodeURIComponent(assertJobId(jobId))}/events/stream`, init);
+    }
+
+    async subscribeToJob<TOutput = unknown>(
+        jobId: string,
+        options?: CloudWebSearchSubscribeOptions<TOutput>,
+    ): Promise<AsyncGenerator<CloudWebSearchStreamEvent<TOutput>>> {
+        const response = await this.streamJob(jobId, options?.init);
+        if (!response.body) {
+            throw new CloudWebSearchStreamProtocolError("Cloud web-search stream response did not include a body");
+        }
+        return readCloudWebSearchEventStream(response.body, options);
+    }
+
+    async subscribeToRichJob<TOutput = unknown>(
+        jobId: string,
+        options?: CloudWebSearchSubscribeOptions<TOutput>,
+    ): Promise<AsyncGenerator<CloudWebSearchRichEvent<TOutput>>> {
+        const events = await this.subscribeToJob(jobId, options);
+
+        async function* richStream() {
+            for await (const event of events) {
+                for (const richEvent of toCloudWebSearchRichEvents(event)) {
+                    yield richEvent;
+                }
+            }
+        }
+
+        return richStream();
+    }
+
+    async waitForCompletion<TOutput = unknown>(
+        jobId: string,
+        options?: WaitForCompletionOptions<TOutput>,
+    ): Promise<CloudWebSearchJobWaitResult<TOutput>> {
+        const normalizedJobId = assertJobId(jobId);
+        const job = await this.transport.poll(
+            () => this.getJob(normalizedJobId, options),
+            {
+                intervalMs: options?.intervalMs,
+                timeoutMs: options?.timeoutMs,
+                isDone: (value: CloudWebSearchJobRecord<TOutput>) => TERMINAL_STATUSES.has(value.status),
+            },
+        );
+
+        if (job.status === "completed") {
+            const envelope = await this.getJobResult(normalizedJobId, options);
+            return {
+                job,
+                result: envelope.result,
+            };
+        }
+
+        if (job.status === "cancelled") {
+            throw new Error(job.errorMessage ?? `Web search job ${normalizedJobId} was cancelled`);
+        }
+
+        throw new Error(job.errorMessage ?? `Web search job ${normalizedJobId} finished with status ${job.status}`);
+    }
+}

package/src/errors.ts

@@ -0,0 +1,20 @@
+export class CloudWebSearchValidationError extends Error {
+    readonly path: string;
+    readonly expected: string;
+    readonly actual: unknown;
+
+    constructor(path: string, expected: string, actual: unknown) {
+        super(`Invalid cloud web-search payload at ${path}: expected ${expected}`);
+        this.name = "CloudWebSearchValidationError";
+        this.path = path;
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+
+export class CloudWebSearchStreamProtocolError extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = "CloudWebSearchStreamProtocolError";
+    }
+}