@opengeni/sdk 3.1.0 → 3.1.2

package/src/chat/http.ts

@@ -0,0 +1,257 @@
+import { OpenGeniApiError } from "../errors";
+import type { Opengeni } from "./opengeni";
+import { OpenGeniChatError, type ChatImportedMessage, type ChatOptions } from "./types";
+
+/** Internal HTTP plumbing shared by the native handler and the protocol adapters. */
+
+/**
+ * Header a client uses to name the conversation it is on. Every handler reads
+ * the client conversation as: the host's resolution, else this header, else
+ * the protocol's own field.
+ */
+export const CHAT_CONVERSATION_HEADER = "x-opengeni-conversation";
+
+const CHAT_ERROR_STATUS: Readonly<Record<string, number>> = {
+  memory_scope_requires_user: 400,
+  conversation_not_authorized: 403,
+  conversation_mismatch: 409,
+};
+
+/** What the host's auth hook returns: identity from the host, conversation optional per protocol. */
+export type ChatResolution = Omit<ChatOptions, "conversation"> & {
+  conversation?: string | undefined;
+};
+
+/**
+ * The host's authentication hook. It receives the raw request and returns the
+ * tenant/user/conversation the caller is allowed to use, or a `Response` to
+ * reject the request. Never derive tenant or user from the request body.
+ */
+export type ChatResolve = (
+  request: Request,
+) => Promise<ChatResolution | Response> | ChatResolution | Response;
+
+export type ChatErrorSummary = { status: number; code: string; message: string };
+
+export function jsonResponse(body: unknown, status = 200, headers: HeadersInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json; charset=utf-8", ...headers },
+  });
+}
+
+export function errorResponse(status: number, message: string, code: string): Response {
+  return jsonResponse(
+    { error: { message, code, type: status >= 500 ? "server_error" : "invalid_request_error" } },
+    status,
+  );
+}
+
+export async function readJsonObject(request: Request): Promise<Record<string, unknown> | null> {
+  try {
+    const parsed: unknown = await request.json();
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function resolveChatRequest(
+  request: Request,
+  resolve: ChatResolve,
+): Promise<{ resolution: ChatResolution; response?: undefined } | { response: Response }> {
+  const resolved = await resolve(request);
+  if (resolved instanceof Response) return { response: resolved };
+  return { resolution: resolved };
+}
+
+/** The client-supplied conversation: the header, else the protocol's own field. */
+export function clientConversation(request: Request, protocolField: unknown): string | undefined {
+  const header = request.headers.get(CHAT_CONVERSATION_HEADER);
+  if (header) return header;
+  return typeof protocolField === "string" && protocolField ? protocolField : undefined;
+}
+
+/**
+ * Open a chat from a resolution plus the conversation the client supplied.
+ * The host names the conversation, or the host names the user and the client
+ * conversation id is namespaced to that user; anything else is a 400, because
+ * an unscoped client id could address any conversation in the workspace.
+ */
+export async function openResolvedChat(
+  og: Opengeni,
+  resolution: ChatResolution,
+  clientConversationId: string | undefined,
+): Promise<
+  { chat: Awaited<ReturnType<Opengeni["chat"]>>; response?: undefined } | { response: Response }
+> {
+  if (!resolution.conversation && !resolution.user) {
+    return {
+      response: errorResponse(
+        400,
+        "Return a conversation from resolve, or a user so client conversation ids are scoped to that user.",
+        "conversation_required",
+      ),
+    };
+  }
+  const conversationId = resolution.conversation ?? clientConversationId;
+  if (!conversationId) {
+    return {
+      response: errorResponse(
+        400,
+        `A conversation id is required: send the ${CHAT_CONVERSATION_HEADER} header or the protocol's conversation field.`,
+        "conversation_required",
+      ),
+    };
+  }
+  try {
+    const chat = await og.chat({ ...resolution, conversation: conversationId } as ChatOptions);
+    return { chat };
+  } catch (error) {
+    const summary = chatErrorSummary(error);
+    return { response: errorResponse(summary.status, summary.message, summary.code) };
+  }
+}
+
+export function chatErrorSummary(error: unknown): ChatErrorSummary {
+  if (error instanceof OpenGeniChatError) {
+    const status = CHAT_ERROR_STATUS[error.code] ?? 502;
+    return { status, code: error.code, message: error.message };
+  }
+  if (error instanceof OpenGeniApiError) {
+    return {
+      status: error.status >= 500 ? 502 : error.status,
+      code: error.code ?? "opengeni_api_error",
+      message: error.message,
+    };
+  }
+  if (error instanceof Error && error.name === "AbortError") {
+    return { status: 499, code: "aborted", message: "The chat request was aborted." };
+  }
+  return { status: 500, code: "internal_error", message: "Chat request failed." };
+}
+
+export function sseHeaders(extra: Record<string, string> = {}): Record<string, string> {
+  return {
+    "Content-Type": "text/event-stream; charset=utf-8",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+    ...extra,
+  };
+}
+
+export function sseLine(data: string, event?: string): string {
+  return `${event ? `event: ${event}\n` : ""}data: ${data}\n\n`;
+}
+
+/**
+ * Pull-based text-to-bytes stream over already-formatted SSE blocks. Upstream
+ * consumption follows downstream demand; cancelling fires `onCancel` so the
+ * producer can abort its Opengeni stream.
+ */
+export function sseByteStream(
+  blocks: AsyncIterable<string>,
+  onCancel?: () => void,
+): ReadableStream<Uint8Array> {
+  const encoder = new TextEncoder();
+  const iterator = blocks[Symbol.asyncIterator]();
+  let cancelled = false;
+  return new ReadableStream<Uint8Array>({
+    pull: async (controller) => {
+      const result = await iterator.next();
+      if (cancelled) return;
+      if (result.done) {
+        controller.close();
+        return;
+      }
+      controller.enqueue(encoder.encode(result.value));
+    },
+    cancel: () => {
+      cancelled = true;
+      onCancel?.();
+      void Promise.resolve(iterator.return?.(undefined)).then(
+        () => undefined,
+        () => undefined,
+      );
+    },
+  });
+}
+
+/** Text from an OpenAI-style message content: a string or `[{ type, text }]` parts. */
+export function messageContentText(content: unknown, partTypes: string[]): string | null {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+  const texts = content
+    .map((part) => {
+      if (!part || typeof part !== "object") return null;
+      const record = part as Record<string, unknown>;
+      return partTypes.includes(String(record.type)) && typeof record.text === "string"
+        ? record.text
+        : null;
+    })
+    .filter((text): text is string => text !== null);
+  return texts.length > 0 ? texts.join("\n") : null;
+}
+
+function lastUserMessageIndex(messages: unknown[]): number {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message && typeof message === "object" && (message as { role?: unknown }).role === "user") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function messageText(
+  message: unknown,
+  partTypes: string[],
+  partsField: "parts" | "content",
+): string | null {
+  if (!message || typeof message !== "object") return null;
+  const record = message as Record<string, unknown>;
+  return (
+    messageContentText(record[partsField], partTypes) ??
+    messageContentText(record.content, partTypes)
+  );
+}
+
+/** The last user-role message's text from an OpenAI/Vercel-style `messages` array. */
+export function lastUserMessageText(
+  messages: unknown,
+  partTypes: string[],
+  partsField: "parts" | "content",
+): string | null {
+  if (!Array.isArray(messages)) return null;
+  const index = lastUserMessageIndex(messages);
+  return index < 0 ? null : messageText(messages[index], partTypes, partsField);
+}
+
+/**
+ * Every user/assistant/system message before the last user message, as
+ * imported history for the first create. Items without a role or text
+ * (tool calls, files) are skipped.
+ */
+export function importedHistoryBefore(
+  messages: unknown,
+  partTypes: string[],
+  partsField: "parts" | "content",
+): ChatImportedMessage[] {
+  if (!Array.isArray(messages)) return [];
+  const lastUser = lastUserMessageIndex(messages);
+  if (lastUser < 0) return [];
+  const imported: ChatImportedMessage[] = [];
+  for (const message of messages.slice(0, lastUser)) {
+    const role = (message as { role?: unknown } | null)?.role;
+    if (role !== "user" && role !== "assistant" && role !== "system") continue;
+    const text = messageText(message, partTypes, partsField);
+    if (text) imported.push({ role, text });
+  }
+  return imported;
+}
+
+export function unixSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}

package/src/chat/ids.ts

@@ -0,0 +1,85 @@
+/**
+ * Deterministic chat identities. A conversation id maps to exactly one
+ * session id per workspace, so any process can address the same session
+ * without storing a mapping, and a double-submitted create collapses through
+ * the idempotency key. The optional legacy label argument is retained only to
+ * reproduce historical addresses. New chat calls do not use it: authorization
+ * is independent of addressing, so collaborators can share a conversation.
+ */
+
+/** The end-user label a conversation is namespaced to: the product `source` plus the opaque user id. */
+export type ChatUserLabel = { source: string; id: string };
+
+/** Fixed RFC 4122 namespace for chat session ids. Never change it. */
+export const CHAT_SESSION_NAMESPACE = "7c1e6d3a-5b2f-4e8a-9d4c-0f3b6a8e2c17";
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** RFC 4122 version 5 (SHA-1) UUID of `name` inside `namespace`. */
+export async function uuidV5(name: string, namespace: string): Promise<string> {
+  const namespaceBytes = parseUuid(namespace);
+  const nameBytes = new TextEncoder().encode(name);
+  const input = new Uint8Array(namespaceBytes.length + nameBytes.length);
+  input.set(namespaceBytes, 0);
+  input.set(nameBytes, namespaceBytes.length);
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-1", input)).slice(0, 16);
+  digest[6] = ((digest[6] ?? 0) & 0x0f) | 0x50;
+  digest[8] = ((digest[8] ?? 0) & 0x3f) | 0x80;
+  return formatUuid(digest);
+}
+
+/**
+ * The session id of `conversation` in `workspaceId`: RFC 4122 v5 of the JSON
+ * tuple `[workspaceId, conversation]`, or `[workspaceId, source, id, conversation]`
+ * when the conversation belongs to an end user. JSON encoding keeps the tuple
+ * unambiguous: an id containing `:` or any other delimiter can never make two
+ * different (user, conversation) pairs share a session.
+ */
+export async function chatSessionId(
+  workspaceId: string,
+  conversation: string,
+  user?: ChatUserLabel | undefined,
+): Promise<string> {
+  return await uuidV5(chatIdentityName(workspaceId, conversation, user), CHAT_SESSION_NAMESPACE);
+}
+
+/** The exact v5 name behind {@link chatSessionId}; exported for tests and audits. */
+export function chatIdentityName(
+  workspaceId: string,
+  conversation: string,
+  user?: ChatUserLabel | undefined,
+): string {
+  return JSON.stringify(
+    user ? [workspaceId, user.source, user.id, conversation] : [workspaceId, conversation],
+  );
+}
+
+/**
+ * The create idempotency key for a chat session: `chat:<sessionId>`. The
+ * session id already encodes the workspace, user label, and conversation as an
+ * unambiguous tuple, so the key inherits that and stays bounded.
+ */
+export function chatIdempotencyKey(sessionId: string): string {
+  return `chat:${sessionId}`;
+}
+
+export function isUuid(value: string): boolean {
+  return UUID_PATTERN.test(value);
+}
+
+function parseUuid(value: string): Uint8Array {
+  if (!UUID_PATTERN.test(value)) {
+    throw new TypeError(`Invalid UUID namespace: ${value}`);
+  }
+  const hex = value.replace(/-/g, "");
+  const bytes = new Uint8Array(16);
+  for (let index = 0; index < 16; index += 1) {
+    bytes[index] = Number.parseInt(hex.slice(index * 2, index * 2 + 2), 16);
+  }
+  return bytes;
+}
+
+function formatUuid(bytes: Uint8Array): string {
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}

package/src/chat/index.ts

@@ -0,0 +1,88 @@
+// @opengeni/sdk/chat: the one-option-object chat facade, a server handler for
+// a product's own chat endpoint, and protocol adapters (native SSE, Vercel AI
+// SDK UI message stream, OpenAI Chat Completions and Responses).
+export type { Chats } from "../chats";
+export { OpenGeniSetupError } from "../errors";
+
+export {
+  Chat,
+  DEFAULT_CHAT_SOURCE,
+  DEFAULT_OPENGENI_BASE_URL,
+  IMPORTED_HISTORY_MAX_CHARS,
+  OpenGeni,
+  Opengeni,
+  formatImportedHistory,
+} from "./opengeni";
+export {
+  OpenGeniChatError,
+  type ChatAgentAccess,
+  type ChatChunk,
+  type ChatImportedMessage,
+  type ChatMemory,
+  type ChatMessage,
+  type ChatOptions,
+  type ChatPending,
+  type ChatReply,
+  type ChatReplyStatus,
+  type ChatRespondInput,
+  type ChatSendOptions,
+  type ChatSessionListOptions,
+  type ChatSnapshot,
+  type ChatTarget,
+  type WorkspaceTarget,
+  type ChatToolStatus,
+  type OpenGeniOptions,
+} from "./types";
+export {
+  CHAT_SESSION_NAMESPACE,
+  chatIdempotencyKey,
+  chatIdentityName,
+  chatSessionId,
+  uuidV5,
+  type ChatUserLabel,
+} from "./ids";
+export {
+  ChatTurnFold,
+  approvalPending,
+  humanInputPending,
+  type ChatFoldStep,
+  type ChatTurnTerminal,
+} from "./fold";
+export {
+  CHAT_CONVERSATION_HEADER,
+  CHAT_FORMAT_HEADER,
+  chatChunksToSseBlocks,
+  chatChunksToSseResponse,
+  chatChunksToSseStream,
+  createChatHandler,
+  handleNativeChatRequest,
+  handleNativeHistoryRequest,
+  handleNativeRespondRequest,
+  parseChatChunkStream,
+  respondInputFromBody,
+  type ChatHandlerFormat,
+  type ChatHandlerOptions,
+  type ChatResolution,
+  type ChatResolve,
+} from "./handler";
+export {
+  UI_MESSAGE_STREAM_HEADER,
+  UI_MESSAGE_STREAM_VERSION,
+  chatChunksToUIMessageStream,
+  handleVercelChatRequest,
+  lastUIMessageText,
+  uiMessageStreamBlocks,
+  uiMessageStreamParts,
+  uiMessageStreamResponse,
+  type UIMessageStreamOptions,
+} from "./vercel";
+export {
+  chatCompletionBlocks,
+  chatCompletionObject,
+  decodeResponseId,
+  encodeResponseId,
+  handleChatCompletionsRequest,
+  handleResponsesRequest,
+  responsesBlocks,
+  responsesInputText,
+} from "./openai";