@kognitivedev/cloud-web-search 0.2.28

package/src/types.ts

@@ -0,0 +1,362 @@
+import type { HttpTransportConfig, LogLevel } from "@kognitivedev/client-core";
+import type { ParsedSSEEvent } from "./sse";
+
+export type { LogLevel };
+
+export interface CloudWebSearchClientConfig extends HttpTransportConfig {}
+
+export type CloudWebSearchJobStatus = "queued" | "in_progress" | "completed" | "error" | "cancelled";
+export type CloudWebSearchMode = "search" | "research";
+export type CloudWebSearchTimeRange = "day" | "week" | "month" | "year";
+
+export type CloudWebSearchOutputParser<TOutput> = (value: unknown) => TOutput;
+
+export interface CloudWebSearchDecodeOptions<TOutput = unknown> {
+    parseOutput?: CloudWebSearchOutputParser<TOutput>;
+}
+
+export interface CloudWebSearchSubscribeOptions<TOutput = unknown> extends CloudWebSearchDecodeOptions<TOutput> {
+    init?: RequestInit;
+}
+
+export interface CloudWebSearchExecutionParameters {
+    maxResults?: number;
+    maxPages?: number;
+    region?: string;
+    timeRange?: CloudWebSearchTimeRange;
+    includeDomains?: string[];
+    excludeDomains?: string[];
+    outputSchema?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+export interface CloudWebSearchSearchJobInput {
+    mode: "search";
+    query: string;
+    parameters?: CloudWebSearchExecutionParameters;
+}
+
+export interface CloudWebSearchResearchJobInput {
+    mode: "research";
+    instructions: string;
+    responseInstructions?: string;
+    responseSchema?: Record<string, unknown>;
+    parameters?: CloudWebSearchExecutionParameters;
+}
+
+export type CreateCloudWebSearchJobInput =
+    | CloudWebSearchSearchJobInput
+    | CloudWebSearchResearchJobInput;
+
+export interface ResearchPlanTodo {
+    id: string;
+    title: string;
+    objective: string;
+    searchQuery?: string;
+    rationale?: string;
+}
+
+export interface ResearchPlan {
+    summary: string;
+    todos: ResearchPlanTodo[];
+}
+
+export interface CloudWebSearchProgressEntry {
+    stage: string;
+    message: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+
+export interface CloudWebSearchSource {
+    title?: string | null;
+    url?: string | null;
+    host?: string | null;
+    snippet?: string | null;
+    relevantContent?: string | null;
+    keyFacts?: string[];
+    confidence?: number | null;
+    score?: number | null;
+    faviconUrl?: string | null;
+}
+
+export interface CloudWebSearchResult<TOutput = unknown> {
+    output?: TOutput;
+    text?: string | null;
+    sources: CloudWebSearchSource[];
+    metadata?: Record<string, unknown>;
+}
+
+export interface CloudWebSearchJobRecord<TOutput = unknown> {
+    id: string;
+    projectId: string;
+    mode: CloudWebSearchMode;
+    searchQuery?: string | null;
+    searchInstructions?: string | null;
+    responseInstructions?: string | null;
+    responseSchema?: Record<string, unknown> | null;
+    researchPlan?: ResearchPlan | null;
+    parameters: Record<string, unknown>;
+    status: CloudWebSearchJobStatus;
+    results?: CloudWebSearchResult<TOutput> | null;
+    progress: CloudWebSearchProgressEntry[];
+    errorMessage?: string | null;
+    cancelRequestedAt?: string | Date | null;
+    cancelledAt?: string | Date | null;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+}
+
+export interface CloudWebSearchJobEventRecord {
+    id: string;
+    jobId: string;
+    projectId: string;
+    eventType: string;
+    stage: string | null;
+    status: string | null;
+    message: string | null;
+    payload: unknown;
+    createdAt: string | Date;
+}
+
+export interface CloudWebSearchJobResultEnvelope<TOutput = unknown> {
+    jobId: string;
+    status: "completed";
+    result: CloudWebSearchResult<TOutput> | null;
+}
+
+export interface WaitForCompletionOptions<TOutput = unknown> extends CloudWebSearchDecodeOptions<TOutput> {
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+
+export interface CloudWebSearchJobWaitResult<TOutput = unknown> {
+    job: CloudWebSearchJobRecord<TOutput>;
+    result: CloudWebSearchResult<TOutput> | null;
+}
+
+export interface CloudWebSearchRichSource extends CloudWebSearchSource {
+    host?: string | null;
+    relevantContent?: string | null;
+    keyFacts?: string[];
+    confidence?: number | null;
+}
+
+export interface CloudWebSearchProductAnswer {
+    kind?: string;
+    markdown?: string;
+    headline?: string;
+    lede?: string;
+    table?: unknown;
+    takeaways?: string[];
+    cites?: Array<Record<string, unknown>>;
+    sources?: CloudWebSearchRichSource[];
+    [key: string]: unknown;
+}
+
+export type CloudWebSearchRichEvent<TOutput = unknown> =
+    | {
+        type: "plan.started";
+        jobId: string;
+        message?: string | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "plan.completed";
+        jobId: string;
+        plan: ResearchPlan | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "todo.generated";
+        jobId: string;
+        todo: ResearchPlanTodo | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "search.started";
+        jobId: string;
+        query: string | null;
+        input?: unknown;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "search.completed";
+        jobId: string;
+        query: string | null;
+        provider?: string | null;
+        results: CloudWebSearchRichSource[];
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "source.opening";
+        jobId: string;
+        source: CloudWebSearchRichSource | null;
+        index?: number | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "source.extracted";
+        jobId: string;
+        source: CloudWebSearchRichSource | null;
+        snippet?: string | null;
+        confidence?: number | null;
+        index?: number | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "source.failed";
+        jobId: string;
+        source: CloudWebSearchRichSource | null;
+        errorMessage: string | null;
+        index?: number | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "reasoning.delta";
+        jobId: string;
+        delta: string;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "answer.delta";
+        jobId: string;
+        delta: string;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "sources.reviewing";
+        jobId: string;
+        totalExtractions?: number | null;
+        message?: string | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "sources.filtered";
+        jobId: string;
+        totalSources?: number | null;
+        credibleSources?: number | null;
+        filteredOut?: number | null;
+        message?: string | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "sources.reviewed";
+        jobId: string;
+        sources: CloudWebSearchRichSource[];
+        credibleSourceCount?: number | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "synthesis.started";
+        jobId: string;
+        totalExtractions?: number | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "synthesis.completed";
+        jobId: string;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "answer.completed";
+        jobId: string;
+        result?: CloudWebSearchResult<TOutput> | null;
+        answer?: CloudWebSearchProductAnswer | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "completed";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        result: CloudWebSearchResult<TOutput> | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "error";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        errorMessage: string;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "cancelled";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    };
+
+export type CloudWebSearchStreamEvent<TOutput = unknown> =
+    | {
+        type: "snapshot";
+        job: CloudWebSearchJobRecord<TOutput>;
+    }
+    | {
+        type: "progress";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        status: CloudWebSearchJobStatus;
+        progress: CloudWebSearchProgressEntry;
+        eventId?: string;
+        replay?: boolean;
+        rawEventType?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "completed";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        result: CloudWebSearchResult<TOutput> | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "error";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        errorMessage: string;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "cancelled";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        eventId?: string;
+        raw?: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "keepalive";
+        jobId: string;
+        timestamp: string;
+    }
+    | {
+        type: "event";
+        jobId: string;
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        event: CloudWebSearchJobEventRecord;
+    }
+    | {
+        type: "unknown";
+        job: CloudWebSearchJobRecord<TOutput> | null;
+        frame: ParsedSSEEvent<unknown>;
+    };