@kognitivedev/cloud-web-search

Cloud web-search SDK for Kognitive's hosted /api/cloud/web-search/* job APIs.

Use it when you want a first-class TypeScript client for:

• creating hosted search and research jobs
• polling current job state
• waiting for completion
• cancelling queued or running jobs
• subscribing to live progress over SSE
• validating server payloads before they reach application code

Installation

bun add @kognitivedev/cloud-web-search

Quick Start

import { KognitiveCloudWebSearchClient } from "@kognitivedev/cloud-web-search";

const webSearch = new KognitiveCloudWebSearchClient({
  baseUrl: process.env.COGNITIVE_API_URL ?? "http://localhost:3001",
  apiKey: process.env.COGNITIVE_API_KEY,
});

const job = await webSearch.jobs.create({
  mode: "research",
  instructions: "Research the latest Bun release updates.",
  responseInstructions: "Return a concise summary.",
  responseSchema: {
    type: "object",
    properties: {
      summary: { type: "string" },
    },
    required: ["summary"],
  },
  parameters: {
    maxPages: 4,
    timeRange: "month",
  },
});

const completed = await webSearch.jobs.waitForCompletion(job.id, {
  parseOutput(value) {
    if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.summary !== "string") {
      throw new Error("Expected { summary: string }");
    }

    return { summary: value.summary };
  },
});

console.log(completed.result?.output?.summary);
console.log(completed.result?.sources);

API Surface

@kognitivedev/cloud-web-search centers on hosted job lifecycle methods:

• jobs.list()
• jobs.create()
• jobs.createSearch()
• jobs.createResearch()
• jobs.get()
• jobs.result()
• jobs.cancel()
• jobs.waitForCompletion()
• jobs.stream()
• jobs.subscribe()
• jobs.streamUrl()

All requests use the same project API key model as the backend cloud web-search endpoints.

Typed Output

jobs.get(), jobs.result(), jobs.waitForCompletion(), and jobs.subscribe() accept parseOutput so you can turn result.output from unknown into a typed shape at the SDK boundary.

const envelope = await webSearch.jobs.result(job.id, {
  parseOutput(value) {
    if (!value || typeof value !== "object" || Array.isArray(value) || typeof value.summary !== "string") {
      throw new Error("Expected { summary: string }");
    }

    return { summary: value.summary };
  },
});

envelope.result?.output?.summary;

Streaming Progress

Use jobs.subscribe() when you want normalized progress events without manually parsing SSE frames:

const stream = await webSearch.jobs.subscribe(job.id);

for await (const event of stream) {
  switch (event.type) {
    case "snapshot":
      console.log("job status:", event.job.status);
      break;
    case "progress":
      console.log(`[${event.progress.stage}] ${event.progress.message}`);
      break;
    case "completed":
      console.log("done:", event.result?.text);
      break;
    case "error":
      console.error(event.errorMessage);
      break;
    case "cancelled":
      console.log("job cancelled");
      break;
    case "event":
      console.log("raw job event:", event.event.eventType);
      break;
    case "unknown":
      console.log("unrecognized frame:", event.frame.event);
      break;
  }
}

The SDK handles both stream shapes the backend can emit:

• canonical lifecycle frames such as job.snapshot, job.progress, and job.completed
• persisted job-event replay frames where the SSE event: name is the stored eventType

The low-level readSSEStream() parser is chunk-safe and supports:

• multi-line data: fields
• CRLF, LF, and CR line endings
• SSE comments
• id: and retry: fields
• EOF flush for the final event

If you want the raw SSE response instead, use:

const response = await webSearch.jobs.stream(job.id);

Polling For Completion

const { job: finalJob, result } = await webSearch.jobs.waitForCompletion(job.id, {
  intervalMs: 1_000,
  timeoutMs: 120_000,
});

console.log(finalJob.status);
console.log(result?.text);

waitForCompletion() polls jobs.get() until the job reaches a terminal state:

• returns { job, result } when the job completes successfully
• throws when the job ends in error
• throws when the job is cancelled

Cancellation

await webSearch.jobs.cancel(job.id);

Cancellation is best-effort at the job layer. Completed, failed, or already-cancelled jobs are returned unchanged by the backend.

Error Model

The SDK fails fast on malformed server payloads instead of returning optimistic casts:

• CloudWebSearchValidationError for invalid REST or stream payloads
• CloudWebSearchStreamProtocolError when the SSE response cannot be consumed as a stream

Related Packages

• @kognitivedev/web-search for the in-process workflow/tool package
• @kognitivedev/flows for hosted cloud-flow APIs