@kognitivedev/cloud-web-search 0.2.28

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @kognitivedev/cloud-web-search
+
+## 0.2.28
+
+### Patch Changes
+
+- add hosted cloud web-search SDK
+- validate REST and SSE payloads at runtime
+- support typed `result.output` parsing via `parseOutput`
+- normalize canonical lifecycle frames and persisted job-event replay streams
+
+- Updated dependencies []:
+  - @kognitivedev/client-core@0.2.28

package/README.md

@@ -0,0 +1,186 @@
+# @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
+
+```bash
+bun add @kognitivedev/cloud-web-search
+```
+
+## Quick Start
+
+```ts
+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.
+
+```ts
+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:
+
+```ts
+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:
+
+```ts
+const response = await webSearch.jobs.stream(job.id);
+```
+
+## Polling For Completion
+
+```ts
+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
+
+```ts
+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

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import { HttpTransport } from "@kognitivedev/client-core";
+import type { CloudWebSearchClientConfig, CloudWebSearchDecodeOptions, CloudWebSearchExecutionParameters, CloudWebSearchJobRecord, CloudWebSearchJobResultEnvelope, CloudWebSearchJobWaitResult, CloudWebSearchResearchJobInput, CloudWebSearchRichEvent, CloudWebSearchSearchJobInput, CloudWebSearchStreamEvent, CloudWebSearchSubscribeOptions, CreateCloudWebSearchJobInput, WaitForCompletionOptions } from "./types";
+export declare function readCloudWebSearchEventStream<TOutput = unknown>(stream: ReadableStream<Uint8Array>, options?: CloudWebSearchDecodeOptions<TOutput>): AsyncGenerator<CloudWebSearchStreamEvent<TOutput>>;
+export declare class KognitiveCloudWebSearchClient {
+    private readonly transport;
+    readonly jobs: {
+        list: <TOutput = unknown>(options?: CloudWebSearchDecodeOptions<TOutput>) => Promise<CloudWebSearchJobRecord<TOutput>[]>;
+        create: (input: CreateCloudWebSearchJobInput) => Promise<CloudWebSearchJobRecord<unknown>>;
+        createSearch: (input: Omit<CloudWebSearchSearchJobInput, "mode"> | string, parameters?: CloudWebSearchExecutionParameters) => Promise<CloudWebSearchJobRecord<unknown>>;
+        createResearch: <TOutput = unknown>(input: Omit<CloudWebSearchResearchJobInput, "mode"> | string, options?: Omit<CloudWebSearchResearchJobInput, "mode" | "instructions">) => Promise<CloudWebSearchJobRecord<TOutput>>;
+        get: <TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>) => Promise<CloudWebSearchJobRecord<TOutput>>;
+        result: <TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>) => Promise<CloudWebSearchJobResultEnvelope<TOutput>>;
+        cancel: <TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>) => Promise<CloudWebSearchJobRecord<TOutput>>;
+        stream: (jobId: string, init?: RequestInit) => Promise<Response>;
+        subscribe: <TOutput = unknown>(jobId: string, options?: CloudWebSearchSubscribeOptions<TOutput>) => Promise<AsyncGenerator<CloudWebSearchStreamEvent<TOutput>, any, any>>;
+        subscribeRich: <TOutput = unknown>(jobId: string, options?: CloudWebSearchSubscribeOptions<TOutput>) => Promise<AsyncGenerator<CloudWebSearchRichEvent<TOutput>, any, any>>;
+        streamUrl: (jobId: string) => string;
+        waitForCompletion: <TOutput = unknown>(jobId: string, options?: WaitForCompletionOptions<TOutput>) => Promise<CloudWebSearchJobWaitResult<TOutput>>;
+    };
+    constructor(config: CloudWebSearchClientConfig | HttpTransport);
+    getJobEventsStreamUrl(jobId: string): string;
+    listJobs<TOutput = unknown>(options?: CloudWebSearchDecodeOptions<TOutput>): Promise<CloudWebSearchJobRecord<TOutput>[]>;
+    createJob(input: CreateCloudWebSearchJobInput): Promise<CloudWebSearchJobRecord>;
+    createSearchJob(input: Omit<CloudWebSearchSearchJobInput, "mode"> | string, parameters?: CloudWebSearchExecutionParameters): Promise<CloudWebSearchJobRecord>;
+    createResearchJob<TOutput = unknown>(input: Omit<CloudWebSearchResearchJobInput, "mode"> | string, options?: Omit<CloudWebSearchResearchJobInput, "mode" | "instructions">): Promise<CloudWebSearchJobRecord<TOutput>>;
+    getJob<TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>): Promise<CloudWebSearchJobRecord<TOutput>>;
+    getJobResult<TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>): Promise<CloudWebSearchJobResultEnvelope<TOutput>>;
+    cancelJob<TOutput = unknown>(jobId: string, options?: CloudWebSearchDecodeOptions<TOutput>): Promise<CloudWebSearchJobRecord<TOutput>>;
+    streamJob(jobId: string, init?: RequestInit): Promise<Response>;
+    subscribeToJob<TOutput = unknown>(jobId: string, options?: CloudWebSearchSubscribeOptions<TOutput>): Promise<AsyncGenerator<CloudWebSearchStreamEvent<TOutput>>>;
+    subscribeToRichJob<TOutput = unknown>(jobId: string, options?: CloudWebSearchSubscribeOptions<TOutput>): Promise<AsyncGenerator<CloudWebSearchRichEvent<TOutput>>>;
+    waitForCompletion<TOutput = unknown>(jobId: string, options?: WaitForCompletionOptions<TOutput>): Promise<CloudWebSearchJobWaitResult<TOutput>>;
+}