@kognitivedev/cloud-web-search 0.2.28

package/dist/validation.js

@@ -0,0 +1,437 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPlainObject = isPlainObject;
+exports.cloneUnknown = cloneUnknown;
+exports.isJobStatus = isJobStatus;
+exports.decodeCloudWebSearchSource = decodeCloudWebSearchSource;
+exports.decodeCloudWebSearchResult = decodeCloudWebSearchResult;
+exports.decodeCloudWebSearchProgressEntry = decodeCloudWebSearchProgressEntry;
+exports.decodeCloudWebSearchJobRecord = decodeCloudWebSearchJobRecord;
+exports.decodeCloudWebSearchJobEventRecord = decodeCloudWebSearchJobEventRecord;
+exports.decodeCloudWebSearchJobListEnvelope = decodeCloudWebSearchJobListEnvelope;
+exports.decodeCloudWebSearchJobResultEnvelope = decodeCloudWebSearchJobResultEnvelope;
+exports.decodeJobSnapshotPayload = decodeJobSnapshotPayload;
+exports.decodeDirectProgressPayload = decodeDirectProgressPayload;
+exports.decodeDirectCompletedPayload = decodeDirectCompletedPayload;
+exports.decodeDirectErrorPayload = decodeDirectErrorPayload;
+exports.decodeDirectCancelledPayload = decodeDirectCancelledPayload;
+exports.decodeKeepalivePayload = decodeKeepalivePayload;
+exports.validateCreateCloudWebSearchJobInput = validateCreateCloudWebSearchJobInput;
+const errors_1 = require("./errors");
+const JOB_STATUSES = new Set(["queued", "in_progress", "completed", "error", "cancelled"]);
+const MODES = new Set(["search", "research"]);
+const TIME_RANGES = new Set(["day", "week", "month", "year"]);
+function isPlainObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function cloneUnknown(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => cloneUnknown(entry));
+    }
+    if (value instanceof Date) {
+        return new Date(value.getTime());
+    }
+    if (isPlainObject(value)) {
+        const cloned = {};
+        for (const [key, entry] of Object.entries(value)) {
+            cloned[key] = cloneUnknown(entry);
+        }
+        return cloned;
+    }
+    return value;
+}
+function isJobStatus(value) {
+    return typeof value === "string" && JOB_STATUSES.has(value);
+}
+function isMode(value) {
+    return typeof value === "string" && MODES.has(value);
+}
+function isTimeRange(value) {
+    return typeof value === "string" && TIME_RANGES.has(value);
+}
+function invalid(path, expected, actual) {
+    throw new errors_1.CloudWebSearchValidationError(path, expected, actual);
+}
+function expectObject(value, path) {
+    if (!isPlainObject(value)) {
+        invalid(path, "object", value);
+    }
+    return value;
+}
+function expectArray(value, path) {
+    if (!Array.isArray(value)) {
+        invalid(path, "array", value);
+    }
+    return value;
+}
+function expectString(value, path) {
+    if (typeof value !== "string") {
+        invalid(path, "string", value);
+    }
+    return value;
+}
+function expectNonEmptyString(value, path) {
+    const stringValue = expectString(value, path).trim();
+    if (!stringValue) {
+        invalid(path, "non-empty string", value);
+    }
+    return stringValue;
+}
+function expectNullableString(value, path) {
+    if (value === null) {
+        return null;
+    }
+    return expectString(value, path);
+}
+function expectOptionalNullableString(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    return expectNullableString(value, path);
+}
+function expectFiniteNumber(value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        invalid(path, "finite number", value);
+    }
+    return value;
+}
+function expectPositiveInteger(value, path) {
+    const numberValue = expectFiniteNumber(value, path);
+    if (!Number.isInteger(numberValue) || numberValue <= 0) {
+        invalid(path, "positive integer", value);
+    }
+    return numberValue;
+}
+function expectOptionalRecord(value, path) {
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    return cloneUnknown(expectObject(value, path));
+}
+function expectOptionalNullableRecord(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return cloneUnknown(expectObject(value, path));
+}
+function expectDateish(value, path) {
+    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, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null) {
+        return null;
+    }
+    return expectDateish(value, path);
+}
+function normalizeTimestamp(value, path) {
+    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(value, options) {
+    if (options === null || options === void 0 ? void 0 : options.parseOutput) {
+        return options.parseOutput(cloneUnknown(value));
+    }
+    return cloneUnknown(value);
+}
+function decodeStringArray(value, path) {
+    return expectArray(value, path).map((entry, index) => expectString(entry, `${path}[${index}]`));
+}
+function decodeCloudWebSearchSource(value, path) {
+    const object = expectObject(value, path);
+    const source = {};
+    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;
+}
+function decodeCloudWebSearchResult(value, options, path = "result") {
+    const object = expectObject(value, path);
+    const sources = expectArray(object.sources, `${path}.sources`).map((source, index) => decodeCloudWebSearchSource(source, `${path}.sources[${index}]`));
+    const result = {
+        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;
+}
+function decodeCloudWebSearchProgressEntry(value, path) {
+    const object = expectObject(value, path);
+    const metadata = expectOptionalRecord(object.metadata, `${path}.metadata`);
+    return Object.assign({ stage: expectNonEmptyString(object.stage, `${path}.stage`), message: expectNonEmptyString(object.message, `${path}.message`), timestamp: normalizeTimestamp(object.timestamp, `${path}.timestamp`) }, (metadata ? { metadata } : {}));
+}
+function decodeResearchPlanTodo(value, path) {
+    const object = expectObject(value, path);
+    return Object.assign(Object.assign({ 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, path) {
+    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}]`)),
+    };
+}
+function decodeCloudWebSearchJobRecord(value, options, path = "job") {
+    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 = {
+        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;
+}
+function decodeCloudWebSearchJobEventRecord(value, path = "event") {
+    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`),
+    };
+}
+function decodeCloudWebSearchJobListEnvelope(value, options, path = "jobs.list") {
+    const object = expectObject(value, path);
+    return {
+        jobs: expectArray(object.jobs, `${path}.jobs`).map((job, index) => decodeCloudWebSearchJobRecord(job, options, `${path}.jobs[${index}]`)),
+    };
+}
+function decodeCloudWebSearchJobResultEnvelope(value, options, path = "jobs.result") {
+    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`),
+    };
+}
+function decodeJobSnapshotPayload(value, options, path = "stream.job.snapshot") {
+    const object = expectObject(value, path);
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+    };
+}
+function decodeDirectProgressPayload(value, path = "stream.job.progress") {
+    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`),
+    };
+}
+function decodeDirectCompletedPayload(value, options, path = "stream.job.completed") {
+    const object = expectObject(value, path);
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+        result: object.result === null
+            ? null
+            : decodeCloudWebSearchResult(object.result, options, `${path}.result`),
+    };
+}
+function decodeDirectErrorPayload(value, options, path = "stream.job.error") {
+    const object = expectObject(value, path);
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+        errorMessage: expectNonEmptyString(object.errorMessage, `${path}.errorMessage`),
+    };
+}
+function decodeDirectCancelledPayload(value, options, path = "stream.job.cancelled") {
+    const object = expectObject(value, path);
+    return {
+        job: decodeCloudWebSearchJobRecord(object.job, options, `${path}.job`),
+    };
+}
+function decodeKeepalivePayload(value, path = "stream.job.keepalive") {
+    const object = expectObject(value, path);
+    return {
+        jobId: expectNonEmptyString(object.jobId, `${path}.jobId`),
+        timestamp: normalizeTimestamp(object.timestamp, `${path}.timestamp`),
+    };
+}
+function decodeExecutionParameters(value, path) {
+    const object = expectObject(value, path);
+    const parameters = {};
+    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;
+}
+function validateCreateCloudWebSearchJobInput(value, path = "input") {
+    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 Object.assign({ 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 Object.assign(Object.assign(Object.assign({ 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/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@kognitivedev/cloud-web-search",
+  "version": "0.2.28",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w --noCheck",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@kognitivedev/client-core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "description": "Cloud web search SDK for Kognitive hosted job APIs",
+  "keywords": [
+    "kognitive",
+    "web-search",
+    "cloud",
+    "sdk",
+    "search",
+    "research"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kognitivedev/kognitive",
+    "directory": "packages/cloud-web-search"
+  },
+  "homepage": "https://kognitive.dev"
+}