@kognitivedev/adapter-chat-kognitive 0.2.29

package/src/index.ts

@@ -0,0 +1,386 @@
+import {
+    buildCanonicalConversationMessages,
+    isModerationErrorPayload,
+    ModerationError,
+    readKognitiveEventStream,
+    type FilePart,
+    type KognitiveContentPart,
+    type KognitiveMessage,
+    type KognitiveUIMessage,
+} from "@kognitivedev/shared";
+import type {
+    ChatBackendAdapter,
+    ChatBackendContext,
+    ChatThreadClient,
+    ThreadCreateInput,
+    ThreadDetail,
+    ThreadMetadata,
+    ThreadSummary,
+} from "@kognitivedev/ui";
+
+export interface KognitiveChatBackendOptions {
+    serverUrl?: string;
+    streamPath?: string | ((context: ChatBackendContext) => string);
+    threadBasePath?: string | ((context: ChatBackendContext) => string);
+    headers?: Record<string, string> | ((context: ChatBackendContext) => Record<string, string> | undefined);
+    fetch?: typeof fetch;
+}
+
+const ABSOLUTE_URL_RE = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+
+function isAbsoluteUrl(value: string): boolean {
+    return ABSOLUTE_URL_RE.test(value);
+}
+
+function resolveServerUrl(serverUrl?: string): string {
+    const resolved = serverUrl ?? "";
+    if (resolved === "/") return "";
+    return resolved.replace(/\/$/, "");
+}
+
+function joinServerPath(serverUrl: string, path: string): string {
+    const normalizedServerUrl = resolveServerUrl(serverUrl);
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    return `${normalizedServerUrl}${normalizedPath}`;
+}
+
+function appendQueryParams(urlString: string, params: Record<string, string | undefined>): string {
+    if (isAbsoluteUrl(urlString)) {
+        const url = new URL(urlString);
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined) {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url.toString();
+    }
+
+    const [pathAndQuery, hash = ""] = urlString.split("#", 2);
+    const [pathname, query = ""] = pathAndQuery.split("?", 2);
+    const searchParams = new URLSearchParams(query);
+
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined) {
+            searchParams.set(key, value);
+        }
+    }
+
+    const nextQuery = searchParams.toString();
+    return `${pathname}${nextQuery ? `?${nextQuery}` : ""}${hash ? `#${hash}` : ""}`;
+}
+
+function resolveTemplate(template: string | ((context: ChatBackendContext) => string) | undefined, context: ChatBackendContext, fallback: string): string {
+    const resolved = typeof template === "function" ? template(context) : template ?? fallback;
+    return resolved.replace(/:agentName/g, encodeURIComponent(context.agentName));
+}
+
+function resolveEndpoint(serverUrl: string, path: string): string {
+    if (isAbsoluteUrl(path)) {
+        return path.replace(/\/$/, "");
+    }
+    return joinServerPath(serverUrl, path);
+}
+
+function resolveAdapterHeaders(context: ChatBackendContext, source?: KognitiveChatBackendOptions["headers"]): Record<string, string> {
+    return {
+        ...(typeof source === "function" ? source(context) ?? {} : source ?? {}),
+        ...(context.headers ?? {}),
+    };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value as Record<string, unknown>
+        : undefined;
+}
+
+function extractInlineFileData(url: string): string | undefined {
+    if (!url.startsWith("data:")) {
+        return undefined;
+    }
+
+    const commaIndex = url.indexOf(",");
+    if (commaIndex === -1) {
+        return undefined;
+    }
+
+    const metadata = url.slice(0, commaIndex);
+    const payload = url.slice(commaIndex + 1);
+
+    if (metadata.includes(";base64")) {
+        return payload;
+    }
+
+    try {
+        return decodeURIComponent(payload);
+    } catch {
+        return payload;
+    }
+}
+
+function serializeRuntimePart(part: KognitiveContentPart): KognitiveContentPart {
+    if (part.type !== "file") {
+        return part;
+    }
+
+    const filePart = part as FilePart;
+    if (filePart.data !== undefined) {
+        return filePart;
+    }
+
+    const inlineData = typeof filePart.url === "string" ? extractInlineFileData(filePart.url) : undefined;
+    if (inlineData === undefined) {
+        return filePart;
+    }
+
+    return {
+        type: "file",
+        data: inlineData,
+        filename: filePart.filename ?? filePart.name,
+        mediaType: filePart.mediaType ?? filePart.mimeType ?? filePart.mime_type,
+    };
+}
+
+function serializeRuntimeMetadata(metadata: KognitiveUIMessage["metadata"]) {
+    if (!metadata || typeof metadata !== "object") {
+        return metadata;
+    }
+
+    const { feedback: _ignoredFeedback, ...rest } = metadata;
+    return Object.keys(rest).length > 0 ? rest : undefined;
+}
+
+function uiMessageToRuntimeMessage(message: KognitiveUIMessage): KognitiveMessage {
+    return {
+        role: message.role,
+        content: message.parts.map(serializeRuntimePart),
+        metadata: serializeRuntimeMetadata(message.metadata),
+    };
+}
+
+async function buildKognitiveTransportError(response: Response): Promise<Error> {
+    const responseText = await response.clone().text();
+    if (responseText !== "") {
+        try {
+            const parsed = JSON.parse(responseText) as unknown;
+            if (isModerationErrorPayload(parsed)) {
+                return new ModerationError(parsed, response.status);
+            }
+
+            if (parsed && typeof parsed === "object" && typeof (parsed as { error?: unknown }).error === "string") {
+                return new Error((parsed as { error: string }).error);
+            }
+        } catch {
+            // fall back to raw text
+        }
+    }
+
+    return new Error(`Kognitive transport failed: HTTP ${response.status}`);
+}
+
+export function createKognitiveChatBackend(options: KognitiveChatBackendOptions = {}): ChatBackendAdapter {
+    const serverUrl = resolveServerUrl(options.serverUrl);
+    const fetchImpl = options.fetch ?? fetch;
+
+    return {
+        capabilities: {
+            threads: true,
+            threadFork: true,
+            threadInterrupt: true,
+            threadDelete: true,
+            threadRename: true,
+            threadArchive: true,
+            messageFeedback: true,
+        },
+        createExecutionClient(context) {
+            const api = resolveEndpoint(
+                serverUrl,
+                resolveTemplate(options.streamPath, context, "/api/kognitive/agents/:agentName/stream"),
+            );
+            const baseHeaders = {
+                "Content-Type": "application/json",
+                ...resolveAdapterHeaders(context, options.headers),
+            };
+
+            return {
+                async stream(request) {
+                    const contextBody = asRecord(context.body);
+                    const requestBody = asRecord(request.body);
+                    const mergedMetadata = {
+                        ...(asRecord(contextBody?.metadata) ?? {}),
+                        ...(asRecord(requestBody?.metadata) ?? {}),
+                    };
+
+                    const response = await fetchImpl(api, {
+                        method: "POST",
+                        headers: baseHeaders,
+                        body: JSON.stringify({
+                            ...(contextBody ?? {}),
+                            ...(requestBody ?? {}),
+                            ...(Object.keys(mergedMetadata).length > 0 ? { metadata: mergedMetadata } : {}),
+                            ...(request.sessionId ? { sessionId: request.sessionId } : {}),
+                            ...(context.runScope ? { runScope: context.runScope } : {}),
+                            ...(context.resourceId ? { resourceId: context.resourceId } : {}),
+                            messages: buildCanonicalConversationMessages(request.messages.map(uiMessageToRuntimeMessage)),
+                        }),
+                        signal: request.signal,
+                    });
+
+                    if (!response.ok) {
+                        throw await buildKognitiveTransportError(response);
+                    }
+
+                    await readKognitiveEventStream(response, async (eventName, data) => {
+                        if (eventName === "messages" || eventName === "custom" || eventName === "debug") {
+                            await request.onEvent(eventName, data);
+                        }
+                    });
+                },
+            };
+        },
+        createThreadClient(context): ChatThreadClient {
+            const apiBase = resolveEndpoint(
+                serverUrl,
+                resolveTemplate(options.threadBasePath, context, "/api/kognitive/threads/agents/:agentName"),
+            ).replace(/\/$/, "");
+            const headers = {
+                "Content-Type": "application/json",
+                ...resolveAdapterHeaders(context, options.headers),
+            };
+            const userId = context.resourceId?.userId ? String(context.resourceId.userId) : undefined;
+            const buildUrl = (path = "") => appendQueryParams(`${apiBase}${path}`, { userId });
+
+            return {
+                async list(query) {
+                    const url = appendQueryParams(buildUrl(), {
+                        userId,
+                        ...(query?.limit !== undefined ? { limit: String(query.limit) } : {}),
+                        ...(query?.offset !== undefined ? { offset: String(query.offset) } : {}),
+                    });
+                    const res = await fetchImpl(url, { headers });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to list threads" }))).error);
+                    }
+                    const data = await res.json();
+                    return {
+                        threads: (data.threads ?? []) as ThreadSummary[],
+                        total: typeof data.total === "number" ? data.total : (data.threads ?? []).length,
+                    };
+                },
+                async get(sessionId) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}`), { headers });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to get thread" }))).error);
+                    }
+                    return (await res.json()) as ThreadDetail;
+                },
+                async create(input) {
+                    const res = await fetchImpl(buildUrl(), {
+                        method: "POST",
+                        headers,
+                        body: JSON.stringify({
+                            ...(userId ? { userId } : {}),
+                            ...(input ?? {}),
+                        }),
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to create thread" }))).error);
+                    }
+                    const data = await res.json();
+                    return data.thread as ThreadSummary;
+                },
+                async fork(sessionId) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}/fork`), {
+                        method: "POST",
+                        headers,
+                        body: JSON.stringify(userId ? { userId } : {}),
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to fork thread" }))).error);
+                    }
+                    const data = await res.json();
+                    return data.thread as ThreadSummary;
+                },
+                async interrupt(sessionId) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}/interrupt`), {
+                        method: "POST",
+                        headers,
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to interrupt thread" }))).error);
+                    }
+                },
+                async delete(sessionId) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}`), {
+                        method: "DELETE",
+                        headers,
+                    });
+                    if (!res.ok && res.status !== 204) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to delete thread" }))).error);
+                    }
+                },
+                async rename(sessionId, title) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}`), {
+                        method: "PATCH",
+                        headers,
+                        body: JSON.stringify({ title }),
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to rename thread" }))).error);
+                    }
+                    const data = await res.json();
+                    return data.thread as ThreadSummary;
+                },
+                async updateMetadata(sessionId: string, metadataPatch: ThreadMetadata) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}`), {
+                        method: "PATCH",
+                        headers,
+                        body: JSON.stringify({ metadataPatch }),
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to update thread metadata" }))).error);
+                    }
+                    const data = await res.json();
+                    return data.thread as ThreadSummary;
+                },
+                async archive(sessionId) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}`), {
+                        method: "PATCH",
+                        headers,
+                        body: JSON.stringify({ archived: true }),
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to archive thread" }))).error);
+                    }
+                    const data = await res.json();
+                    return data.thread as ThreadSummary;
+                },
+                async unarchive(sessionId) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}`), {
+                        method: "PATCH",
+                        headers,
+                        body: JSON.stringify({ archived: false }),
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to unarchive thread" }))).error);
+                    }
+                    const data = await res.json();
+                    return data.thread as ThreadSummary;
+                },
+                async setMessageFeedback(sessionId, messageId, value) {
+                    const res = await fetchImpl(buildUrl(`/${encodeURIComponent(sessionId)}/messages/${encodeURIComponent(messageId)}/feedback`), {
+                        method: "PUT",
+                        headers,
+                        body: JSON.stringify({ value }),
+                    });
+                    if (!res.ok) {
+                        throw new Error((await res.json().catch(() => ({ error: "Failed to set message feedback" }))).error);
+                    }
+                },
+            };
+        },
+    };
+}
+
+export const createKognitiveUIChatBackend = createKognitiveChatBackend;
+export type KognitiveUIChatBackendOptions = KognitiveChatBackendOptions;

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "jsx": "react-jsx",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src"]
+}