@kognitivedev/cloud-web-search 0.2.28

package/src/validation.ts

@@ -0,0 +1,575 @@
+import { CloudWebSearchValidationError } from "./errors";
+import type {
+    CloudWebSearchDecodeOptions,
+    CloudWebSearchExecutionParameters,
+    CloudWebSearchJobEventRecord,
+    CloudWebSearchJobRecord,
+    CloudWebSearchJobResultEnvelope,
+    CloudWebSearchJobStatus,
+    CloudWebSearchMode,
+    CloudWebSearchProgressEntry,
+    CloudWebSearchResult,
+    CloudWebSearchSource,
+    CloudWebSearchTimeRange,
+    CreateCloudWebSearchJobInput,
+    ResearchPlan,
+    ResearchPlanTodo,
+} from "./types";
+
+const JOB_STATUSES = new Set<CloudWebSearchJobStatus>(["queued", "in_progress", "completed", "error", "cancelled"]);
+const MODES = new Set<CloudWebSearchMode>(["search", "research"]);
+const TIME_RANGES = new Set<CloudWebSearchTimeRange>(["day", "week", "month", "year"]);
+
+type PlainObject = Record<string, unknown>;
+
+export function isPlainObject(value: unknown): value is PlainObject {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+
+export function cloneUnknown<T>(value: T): T {
+    if (Array.isArray(value)) {
+        return value.map((entry) => cloneUnknown(entry)) as T;
+    }
+    if (value instanceof Date) {
+        return new Date(value.getTime()) as T;
+    }
+    if (isPlainObject(value)) {
+        const cloned: Record<string, unknown> = {};
+        for (const [key, entry] of Object.entries(value)) {
+            cloned[key] = cloneUnknown(entry);
+        }
+        return cloned as T;
+    }
+    return value;
+}
+
+export function isJobStatus(value: unknown): value is CloudWebSearchJobStatus {
+    return typeof value === "string" && JOB_STATUSES.has(value as CloudWebSearchJobStatus);
+}
+
+function isMode(value: unknown): value is CloudWebSearchMode {
+    return typeof value === "string" && MODES.has(value as CloudWebSearchMode);
+}
+
+function isTimeRange(value: unknown): value is CloudWebSearchTimeRange {
+    return typeof value === "string" && TIME_RANGES.has(value as CloudWebSearchTimeRange);
+}
+
+function invalid(path: string, expected: string, actual: unknown): never {
+    throw new CloudWebSearchValidationError(path, expected, actual);
+}
+
+function expectObject(value: unknown, path: string): PlainObject {
+    if (!isPlainObject(value)) {
+        invalid(path, "object", value);
+    }
+    return value;
+}
+
+function expectArray(value: unknown, path: string): unknown[] {
+    if (!Array.isArray(value)) {
+        invalid(path, "array", value);
+    }
+    return value;
+}
+
+function expectString(value: unknown, path: string): string {
+    if (typeof value !== "string") {
+        invalid(path, "string", value);
+    }
+    return value;
+}
+
+function expectNonEmptyString(value: unknown, path: string): string {
+    const stringValue = expectString(value, path).trim();
+    if (!stringValue) {
+        invalid(path, "non-empty string", value);
+    }
+    return stringValue;
+}
+
+function expectNullableString(value: unknown, path: string): string | null {
+    if (value === null) {
+        return null;
+    }
+    return expectString(value, path);
+}
+
+function expectOptionalNullableString(value: unknown, path: string): string | null | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    return expectNullableString(value, path);
+}
+
+function expectFiniteNumber(value: unknown, path: string): number {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        invalid(path, "finite number", value);
+    }
+    return value;
+}
+
+function expectPositiveInteger(value: unknown, path: string): number {
+    const numberValue = expectFiniteNumber(value, path);
+    if (!Number.isInteger(numberValue) || numberValue <= 0) {
+        invalid(path, "positive integer", value);
+    }
+    return numberValue;
+}
+
+function expectOptionalRecord(value: unknown, path: string): Record<string, unknown> | undefined {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return cloneUnknown(expectObject(value, path));
+}
+
+function expectOptionalNullableRecord(value: unknown, path: string): Record<string, unknown> | null | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return cloneUnknown(expectObject(value, path));
+}
+
+function expectDateish(value: unknown, path: string): string | Date {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return new Date(value.getTime());
+    }
+    invalid(path, "ISO timestamp string or Date", value);
+}
+
+function expectOptionalNullableDateish(value: unknown, path: string): string | Date | null | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return expectDateish(value, path);
+}
+
+function normalizeTimestamp(value: unknown, path: string): string {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value instanceof Date && !Number.isNaN(value.getTime())) {
+        return value.toISOString();
+    }
+    invalid(path, "ISO timestamp string or Date", value);
+}
+
+function parseOutput<TOutput>(
+    value: unknown,
+    options: CloudWebSearchDecodeOptions<TOutput> | undefined,
+): TOutput {
+    if (options?.parseOutput) {
+        return options.parseOutput(cloneUnknown(value));
+    }
+    return cloneUnknown(value) as TOutput;
+}
+
+function decodeStringArray(value: unknown, path: string): string[] {
+    return expectArray(value, path).map((entry, index) => expectString(entry, `${path}[${index}]`));
+}
+
+export function decodeCloudWebSearchSource(value: unknown, path: string): CloudWebSearchSource {
+    const object = expectObject(value, path);
+    const source: CloudWebSearchSource = {};
+
+    if ("title" in object) {
+        source.title = object.title === null ? null : expectString(object.title, `${path}.title`);
+    }
+    if ("url" in object) {
+        source.url = object.url === null ? null : expectString(object.url, `${path}.url`);
+    }
+    if ("host" in object) {
+        source.host = object.host === null ? null : expectString(object.host, `${path}.host`);
+    }
+    if ("snippet" in object) {
+        source.snippet = object.snippet === null ? null : expectString(object.snippet, `${path}.snippet`);
+    }
+    if ("relevantContent" in object) {
+        source.relevantContent = object.relevantContent === null
+            ? null
+            : expectString(object.relevantContent, `${path}.relevantContent`);
+    }
+    if ("keyFacts" in object) {
+        source.keyFacts = decodeStringArray(object.keyFacts, `${path}.keyFacts`);
+    }
+    if ("confidence" in object) {
+        if (object.confidence === null) {
+            source.confidence = null;
+        } else {
+            source.confidence = expectFiniteNumber(object.confidence, `${path}.confidence`);
+        }
+    }
+    if ("score" in object) {
+        if (object.score === null) {
+            source.score = null;
+        } else {
+            source.score = expectFiniteNumber(object.score, `${path}.score`);
+        }
+    }
+    if ("faviconUrl" in object) {
+        source.faviconUrl = object.faviconUrl === null ? null : expectString(object.faviconUrl, `${path}.faviconUrl`);
+    }
+
+    return source;
+}
+
+export function decodeCloudWebSearchResult<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "result",
+): CloudWebSearchResult<TOutput> {
+    const object = expectObject(value, path);
+    const sources = expectArray(object.sources, `${path}.sources`).map((source, index) =>
+        decodeCloudWebSearchSource(source, `${path}.sources[${index}]`));
+
+    const result: CloudWebSearchResult<TOutput> = {
+        sources,
+    };
+
+    if ("output" in object) {
+        result.output = parseOutput(object.output, options);
+    }
+    if ("text" in object) {
+        result.text = object.text === null ? null : expectString(object.text, `${path}.text`);
+    }
+
+    const metadata = expectOptionalRecord(object.metadata, `${path}.metadata`);
+    if (metadata !== undefined) {
+        result.metadata = metadata;
+    }
+
+    return result;
+}
+
+export function decodeCloudWebSearchProgressEntry(value: unknown, path: string): CloudWebSearchProgressEntry {
+    const object = expectObject(value, path);
+    const metadata = expectOptionalRecord(object.metadata, `${path}.metadata`);
+
+    return {
+        stage: expectNonEmptyString(object.stage, `${path}.stage`),
+        message: expectNonEmptyString(object.message, `${path}.message`),
+        timestamp: normalizeTimestamp(object.timestamp, `${path}.timestamp`),
+        ...(metadata ? { metadata } : {}),
+    };
+}
+
+function decodeResearchPlanTodo(value: unknown, path: string): ResearchPlanTodo {
+    const object = expectObject(value, path);
+
+    return {
+        id: expectNonEmptyString(object.id, `${path}.id`),
+        title: expectNonEmptyString(object.title, `${path}.title`),
+        objective: expectNonEmptyString(object.objective, `${path}.objective`),
+        ...(object.searchQuery === undefined ? {} : {
+            searchQuery: expectString(object.searchQuery, `${path}.searchQuery`),
+        }),
+        ...(object.rationale === undefined ? {} : {
+            rationale: expectString(object.rationale, `${path}.rationale`),
+        }),
+    };
+}
+
+function decodeResearchPlan(value: unknown, path: string): ResearchPlan {
+    const object = expectObject(value, path);
+
+    return {
+        summary: expectNonEmptyString(object.summary, `${path}.summary`),
+        todos: expectArray(object.todos, `${path}.todos`).map((todo, index) =>
+            decodeResearchPlanTodo(todo, `${path}.todos[${index}]`)),
+    };
+}
+
+export function decodeCloudWebSearchJobRecord<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "job",
+): CloudWebSearchJobRecord<TOutput> {
+    const object = expectObject(value, path);
+    const mode = object.mode;
+    if (!isMode(mode)) {
+        invalid(`${path}.mode`, "\"search\" or \"research\"", mode);
+    }
+    const status = object.status;
+    if (!isJobStatus(status)) {
+        invalid(`${path}.status`, "\"queued\", \"in_progress\", \"completed\", \"error\", or \"cancelled\"", status);
+    }
+
+    const record: CloudWebSearchJobRecord<TOutput> = {
+        id: expectNonEmptyString(object.id, `${path}.id`),
+        projectId: expectNonEmptyString(object.projectId, `${path}.projectId`),
+        mode,
+        parameters: cloneUnknown(expectObject(object.parameters, `${path}.parameters`)),
+        status,
+        progress: expectArray(object.progress, `${path}.progress`).map((entry, index) =>
+            decodeCloudWebSearchProgressEntry(entry, `${path}.progress[${index}]`)),
+        createdAt: expectDateish(object.createdAt, `${path}.createdAt`),
+        updatedAt: expectDateish(object.updatedAt, `${path}.updatedAt`),
+    };
+
+    if ("searchQuery" in object) {
+        record.searchQuery = expectOptionalNullableString(object.searchQuery, `${path}.searchQuery`);
+    }
+    if ("searchInstructions" in object) {
+        record.searchInstructions = expectOptionalNullableString(object.searchInstructions, `${path}.searchInstructions`);
+    }
+    if ("responseInstructions" in object) {
+        record.responseInstructions = expectOptionalNullableString(object.responseInstructions, `${path}.responseInstructions`);
+    }
+    if ("responseSchema" in object) {
+        record.responseSchema = expectOptionalNullableRecord(object.responseSchema, `${path}.responseSchema`);
+    }
+    if ("researchPlan" in object) {
+        record.researchPlan = object.researchPlan === null
+            ? null
+            : decodeResearchPlan(object.researchPlan, `${path}.researchPlan`);
+    }
+    if ("results" in object) {
+        record.results = object.results === null
+            ? null
+            : decodeCloudWebSearchResult(object.results, options, `${path}.results`);
+    }
+    if ("errorMessage" in object) {
+        record.errorMessage = expectOptionalNullableString(object.errorMessage, `${path}.errorMessage`);
+    }
+    if ("cancelRequestedAt" in object) {
+        record.cancelRequestedAt = expectOptionalNullableDateish(object.cancelRequestedAt, `${path}.cancelRequestedAt`);
+    }
+    if ("cancelledAt" in object) {
+        record.cancelledAt = expectOptionalNullableDateish(object.cancelledAt, `${path}.cancelledAt`);
+    }
+
+    return record;
+}
+
+export function decodeCloudWebSearchJobEventRecord(
+    value: unknown,
+    path = "event",
+): CloudWebSearchJobEventRecord {
+    const object = expectObject(value, path);
+
+    return {
+        id: expectNonEmptyString(object.id, `${path}.id`),
+        jobId: expectNonEmptyString(object.jobId, `${path}.jobId`),
+        projectId: expectNonEmptyString(object.projectId, `${path}.projectId`),
+        eventType: expectNonEmptyString(object.eventType, `${path}.eventType`),
+        stage: expectNullableString(object.stage, `${path}.stage`),
+        status: expectNullableString(object.status, `${path}.status`),
+        message: expectNullableString(object.message, `${path}.message`),
+        payload: cloneUnknown(object.payload),
+        createdAt: expectDateish(object.createdAt, `${path}.createdAt`),
+    };
+}
+
+export function decodeCloudWebSearchJobListEnvelope<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "jobs.list",
+): { jobs: CloudWebSearchJobRecord<TOutput>[] } {
+    const object = expectObject(value, path);
+
+    return {
+        jobs: expectArray(object.jobs, `${path}.jobs`).map((job, index) =>
+            decodeCloudWebSearchJobRecord(job, options, `${path}.jobs[${index}]`)),
+    };
+}
+
+export function decodeCloudWebSearchJobResultEnvelope<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "jobs.result",
+): CloudWebSearchJobResultEnvelope<TOutput> {
+    const object = expectObject(value, path);
+
+    return {
+        jobId: expectNonEmptyString(object.jobId, `${path}.jobId`),
+        status: expectString(object.status, `${path}.status`) === "completed"
+            ? "completed"
+            : invalid(`${path}.status`, "\"completed\"", object.status),
+        result: object.result === null
+            ? null
+            : decodeCloudWebSearchResult(object.result, options, `${path}.result`),
+    };
+}
+
+export function decodeJobSnapshotPayload<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "stream.job.snapshot",
+): { job: CloudWebSearchJobRecord<TOutput> } {
+    const object = expectObject(value, path);
+
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+    };
+}
+
+export function decodeDirectProgressPayload(
+    value: unknown,
+    path = "stream.job.progress",
+): { jobId: string; status: CloudWebSearchJobStatus; progress: CloudWebSearchProgressEntry } {
+    const object = expectObject(value, path);
+    const status = object.status;
+    if (!isJobStatus(status)) {
+        invalid(`${path}.status`, "\"queued\", \"in_progress\", \"completed\", \"error\", or \"cancelled\"", status);
+    }
+
+    return {
+        jobId: expectNonEmptyString(object.jobId, `${path}.jobId`),
+        status,
+        progress: decodeCloudWebSearchProgressEntry(object.progress, `${path}.progress`),
+    };
+}
+
+export function decodeDirectCompletedPayload<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "stream.job.completed",
+): { job: CloudWebSearchJobRecord<TOutput>; result: CloudWebSearchResult<TOutput> | null } {
+    const object = expectObject(value, path);
+
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+        result: object.result === null
+            ? null
+            : decodeCloudWebSearchResult(object.result, options, `${path}.result`),
+    };
+}
+
+export function decodeDirectErrorPayload<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "stream.job.error",
+): { job: CloudWebSearchJobRecord<TOutput>; errorMessage: string } {
+    const object = expectObject(value, path);
+
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+        errorMessage: expectNonEmptyString(object.errorMessage, `${path}.errorMessage`),
+    };
+}
+
+export function decodeDirectCancelledPayload<TOutput = unknown>(
+    value: unknown,
+    options?: CloudWebSearchDecodeOptions<TOutput>,
+    path = "stream.job.cancelled",
+): { job: CloudWebSearchJobRecord<TOutput> } {
+    const object = expectObject(value, path);
+
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+    };
+}
+
+export function decodeKeepalivePayload(
+    value: unknown,
+    path = "stream.job.keepalive",
+): { jobId: string; timestamp: string } {
+    const object = expectObject(value, path);
+
+    return {
+        jobId: expectNonEmptyString(object.jobId, `${path}.jobId`),
+        timestamp: normalizeTimestamp(object.timestamp, `${path}.timestamp`),
+    };
+}
+
+function decodeExecutionParameters(
+    value: unknown,
+    path: string,
+): CloudWebSearchExecutionParameters {
+    const object = expectObject(value, path);
+    const parameters: CloudWebSearchExecutionParameters = {};
+
+    for (const [key, entry] of Object.entries(object)) {
+        switch (key) {
+            case "maxResults":
+            case "maxPages":
+                parameters[key] = expectPositiveInteger(entry, `${path}.${key}`);
+                break;
+            case "region":
+                parameters.region = expectNonEmptyString(entry, `${path}.region`);
+                break;
+            case "timeRange":
+                if (!isTimeRange(entry)) {
+                    invalid(`${path}.timeRange`, "\"day\", \"week\", \"month\", or \"year\"", entry);
+                }
+                parameters.timeRange = entry;
+                break;
+            case "includeDomains":
+                parameters.includeDomains = decodeStringArray(entry, `${path}.includeDomains`);
+                break;
+            case "excludeDomains":
+                parameters.excludeDomains = decodeStringArray(entry, `${path}.excludeDomains`);
+                break;
+            case "outputSchema":
+                parameters.outputSchema = cloneUnknown(expectObject(entry, `${path}.outputSchema`));
+                break;
+            default:
+                parameters[key] = cloneUnknown(entry);
+        }
+    }
+
+    return parameters;
+}
+
+export function validateCreateCloudWebSearchJobInput(
+    value: CreateCloudWebSearchJobInput,
+    path = "input",
+): CreateCloudWebSearchJobInput {
+    const object = expectObject(value, path);
+    const mode = object.mode;
+    if (!isMode(mode)) {
+        invalid(`${path}.mode`, "\"search\" or \"research\"", mode);
+    }
+
+    if (mode === "search") {
+        if ("instructions" in object) {
+            invalid(`${path}.instructions`, "field to be omitted in search mode", object.instructions);
+        }
+        if ("responseInstructions" in object) {
+            invalid(`${path}.responseInstructions`, "field to be omitted in search mode", object.responseInstructions);
+        }
+        if ("responseSchema" in object) {
+            invalid(`${path}.responseSchema`, "field to be omitted in search mode", object.responseSchema);
+        }
+
+        return {
+            mode,
+            query: expectNonEmptyString(object.query, `${path}.query`),
+            ...(object.parameters === undefined ? {} : {
+                parameters: decodeExecutionParameters(object.parameters, `${path}.parameters`),
+            }),
+        };
+    }
+
+    if ("query" in object) {
+        invalid(`${path}.query`, "field to be omitted in research mode", object.query);
+    }
+
+    return {
+        mode,
+        instructions: expectNonEmptyString(object.instructions, `${path}.instructions`),
+        ...(object.responseInstructions === undefined ? {} : {
+            responseInstructions: expectNonEmptyString(object.responseInstructions, `${path}.responseInstructions`),
+        }),
+        ...(object.responseSchema === undefined ? {} : {
+            responseSchema: cloneUnknown(expectObject(object.responseSchema, `${path}.responseSchema`)),
+        }),
+        ...(object.parameters === undefined ? {} : {
+            parameters: decodeExecutionParameters(object.parameters, `${path}.parameters`),
+        }),
+    };
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "module": "commonjs",
+        "rootDir": "src",
+        "outDir": "dist",
+        "declaration": true,
+        "noEmit": false,
+        "incremental": false
+    },
+    "include": ["src"],
+    "exclude": ["src/__tests__"]
+}

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+    test: {
+        globals: true,
+        environment: "node",
+    },
+});