@opengeni/sdk 3.7.0-canary.5 → 3.7.0-canary.7

package/README.md

@@ -18,6 +18,82 @@ bearer design, but an organization API key belongs on the product server.
 Browser cookies are accepted cross-origin only from operator-configured trusted
 origins; arbitrary embedding origins never receive credentialed CORS responses.
 
+## Chat quick start (`@opengeni/sdk/chat`)
+
+The fastest way to put OpenGeni behind an existing chat: one option object per
+conversation, one server handler for your endpoint. Tenants map to organization
+workspaces, conversations map to deterministic sessions, and the organization
+API key never leaves your server.
+
+```ts
+import { OpenGeni, createChatHandler } from "@opengeni/sdk/chat";
+
+const og = new OpenGeni({
+  apiKey: process.env.OPENGENI_API_KEY!,
+  organizationId: process.env.OPENGENI_ORGANIZATION_ID!,
+  // baseUrl defaults to https://app.opengeni.ai; source (default "app") labels your product.
+});
+
+const chat = await og.chat({
+  tenant: "acme", // one workspace per customer, created on first use
+  user: "u_42", // opaque end-user label (required for memory: "user")
+  conversation: "c_9", // stable id, namespaced to user; the session id is derived from both
+  agentAccess: "session", // "session" (default) | "user" | "workspace"
+  memory: "user", // "session" | "user" | "workspace" | false; default follows agentAccess
+  create: { sandboxBackend: "none" }, // raw create-request passthrough for a pure chat
+});
+
+const reply = await chat.send("hello"); // creates the session on the first send
+console.log(reply.text); // or String(reply)
+
+for await (const chunk of chat.stream("and then?")) {
+  if (chunk.type === "text") process.stdout.write(chunk.text);
+  if (chunk.type === "pending") await chat.respond({ requestId: chunk.pending.requestId, decision: "approve" });
+}
+
+// Your endpoint. `resolve` is your auth hook: identity comes from the request
+// you authenticated, never from the body. The handler reads the client's
+// conversation id itself (x-opengeni-conversation header, or the wire format's
+// own field) and scopes it to `user`; return `conversation` from resolve only
+// when the host names it, which is required when there is no `user`.
+export const handler = createChatHandler(og, {
+  resolve: async (request) => {
+    const session = await getSessionFromCookie(request);
+    if (!session) return new Response("Unauthorized", { status: 401 });
+    return { tenant: session.accountId, user: session.userId };
+  },
+  // format: "vercel" | "openai-chat" | "openai-responses" (default "native");
+  // a request may override it with the x-opengeni-chat-format header.
+});
+export const GET = handler; // conversation history, for restoring the chat on reload
+export const POST = handler; // send a message, or answer a pending request at .../respond
+```
+
+Conversation ids are namespaced per user: the same `conversation` for two
+`user` labels reaches two sessions, so a client cannot continue another user's
+chat by guessing its id. Without a `user`, the host must name the conversation
+from `resolve`. The Vercel and OpenAI adapters send only the latest user
+message; the earlier messages in that request are imported once, as context on
+the first message of a conversation, after which OpenGeni owns the history.
+
+Pick the isolation per session with `agentAccess` (which other sessions the
+agent may reach) and `memory` (what it remembers), all inside one workspace that
+shares the customer's documents, instructions, and integrations:
+
+| Scenario                                          | `agentAccess` | `memory`      |
+| ------------------------------------------------- | ------------- | ------------- |
+| Every chat isolated (support desk)                | `"session"`   | `"session"`   |
+| One user's chats see each other, not other users' | `"user"`      | `"user"`      |
+| Everything in the tenant shared                   | `"workspace"` | `"workspace"` |
+| Shared agent access, no memory                    | any           | `false`       |
+
+`<OpenGeniChat handlerUrl="/api/chat" conversation="c_9" />` from
+`@opengeni/react/chat` is the browser component to swap in for your chat box:
+it talks only to your handler, sends the conversation id as the
+`x-opengeni-conversation` header, and restores the history on reload. Graduate
+to `OpenGeniClient` below when you need the full session surface: files, tools,
+approvals with policies, forks, realtime voice.
+
 ## Quick start
 
 ```ts
@@ -76,7 +152,14 @@ complete organization-workspace inventory.
 Organization key administration uses `listOrganizationApiKeys`,
 `createOrganizationApiKey`, and `deleteOrganizationApiKey`. The key token from a
 create response is shown once and must be stored in the backend's secret
-manager.
+manager. `createOrganizationApiKey(organizationId, { name, access: "read" })`
+mints a read-only master key: it inventories shared workspaces and reads their
+sessions, events, and files, but cannot create sessions, send messages, or mint
+keys, and every key reports its tier as `apiKey.access`. Either tier can call
+`listOrganizationSessions(organizationId, { limit, cursor, endUser, status })`
+for one page of sessions across every shared workspace (each row carries its
+`workspaceId`; private sessions and Personal workspaces never appear), or
+`iterateOrganizationSessions` to follow `nextCursor` to the end.
 
 The external backend also owns its Skill catalog. Load the selected definitions
 and pass them inline in `CreateSessionRequest.skills` for each product-created

package/dist/artifacts.js

@@ -1,10 +1,10 @@
 import {
   OpenGeniClient
-} from "./chunk-BFAP54AB.js";
-import "./chunk-5EXQM7D3.js";
-import "./chunk-KKLG2S4L.js";
+} from "./chunk-5PCW44P6.js";
+import "./chunk-XOTTWRJJ.js";
+import "./chunk-UAXA2UKI.js";
 import "./chunk-QTBAMHEF.js";
-import "./chunk-IKOCZY4A.js";
+import "./chunk-VQTDKVIG.js";
 import "./chunk-OO5LPTO7.js";
 export {
   OpenGeniClient

package/dist/browser.js

@@ -8,12 +8,12 @@ import {
 } from "./chunk-FMLDFJ2Q.js";
 import {
   OpenGeniClient
-} from "./chunk-KKLG2S4L.js";
+} from "./chunk-UAXA2UKI.js";
 import "./chunk-QTBAMHEF.js";
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION
-} from "./chunk-IKOCZY4A.js";
+} from "./chunk-VQTDKVIG.js";
 import {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,

package/dist/chat/fold.d.ts

@@ -0,0 +1,46 @@
+import type { SessionEvent } from "../types.js";
+import { OpenGeniChatError, type ChatChunk, type ChatPending, type ChatReply } from "./types.js";
+/**
+ * Event folding shared by `send`, `stream`, and every protocol adapter.
+ *
+ * One fold covers one logical turn: text deltas accumulate into message
+ * segments (a tool call closes the current segment, the completed event
+ * reconciles it), tool call/output pairs become tool chunks, and the turn
+ * settles on a terminal event or a human wait. Events that carry a different
+ * turn id than the expected one are ignored so a queued follow-up never ends
+ * early on the previous turn's settlement.
+ */
+export type ChatTurnTerminal = "completed" | "failed" | "cancelled" | "pending";
+export type ChatFoldStep = {
+    chunks: ChatChunk[];
+    terminal: ChatTurnTerminal | null;
+};
+/** Incremental replay of unresolved requests, without retaining the event log. */
+export declare class ChatPendingFold {
+    private readonly requests;
+    push(event: SessionEvent): void;
+    pending(now?: number): ChatPending[];
+    private put;
+}
+export declare class ChatTurnFold {
+    private readonly workspaceId;
+    private readonly sessionId;
+    readonly events: SessionEvent[];
+    turnId: string | null;
+    pending: ChatPending | null;
+    failure: SessionEvent | null;
+    private readonly segments;
+    private readonly openTools;
+    constructor(workspaceId: string, sessionId: string, expectedTurnId: string | null);
+    get text(): string;
+    push(event: SessionEvent): ChatFoldStep;
+    reply(terminal: ChatTurnTerminal): ChatReply;
+    /** The error to throw for a `turn.failed` settlement. */
+    failureError(): OpenGeniChatError;
+    private closeSegment;
+    private startSegment;
+}
+export declare function approvalPending(payload: Record<string, unknown>): ChatPending | null;
+export declare function humanInputPending(payload: Record<string, unknown>): ChatPending | null;
+export declare function asRecord(value: unknown): Record<string, unknown>;
+export declare function stringValue(value: unknown): string | undefined;

package/dist/chat/handler.d.ts

@@ -0,0 +1,39 @@
+import { type ChatResolve } from "./http.js";
+import type { OpenGeni } from "./opengeni.js";
+import { type ChatChunk, type ChatRespondInput } from "./types.js";
+export { CHAT_CONVERSATION_HEADER, type ChatResolution, type ChatResolve } from "./http.js";
+export type ChatHandlerFormat = "native" | "vercel" | "openai-chat" | "openai-responses";
+export type ChatHandlerOptions = {
+    /** Mandatory host auth hook; see {@link ChatResolve}. */
+    resolve: ChatResolve;
+    /** Default wire format; a request may override it with the format header. */
+    format?: ChatHandlerFormat | undefined;
+};
+/** Per-request wire-format override header. */
+export declare const CHAT_FORMAT_HEADER = "x-opengeni-chat-format";
+/**
+ * One request handler for a product's chat endpoint. `POST` with `{ message }`
+ * streams the reply in the selected format; `POST .../respond` answers a
+ * pending approval or human-input request and streams the continuation;
+ * `GET` returns the conversation's history as JSON. Every other method is a
+ * 405. The conversation is the host's resolution, else the
+ * `x-opengeni-conversation` header, else the wire format's own field.
+ */
+export declare function createChatHandler(og: OpenGeni, options: ChatHandlerOptions): (request: Request) => Promise<Response>;
+/** `POST { message }` -> native SSE of {@link ChatChunk} (`event: chunk`). */
+export declare function handleNativeChatRequest(og: OpenGeni, request: Request, resolve: ChatResolve): Promise<Response>;
+/**
+ * `GET` -> `{ conversation, sessionId, created, messages, pending, status }`: the user and
+ * assistant text of the conversation so a client can restore it on reload
+ * (`messages` is empty and `created` false before the first message).
+ */
+export declare function handleNativeHistoryRequest(og: OpenGeni, request: Request, resolve: ChatResolve): Promise<Response>;
+/** `POST .../respond { requestId, decision | answers | skip }` -> native SSE of the continuation. */
+export declare function handleNativeRespondRequest(og: OpenGeni, request: Request, resolve: ChatResolve): Promise<Response>;
+export declare function respondInputFromBody(body: Record<string, unknown> | null): ChatRespondInput | null;
+/** Native wire format: `event: chunk` per {@link ChatChunk}, `event: error` on failure. */
+export declare function chatChunksToSseBlocks(chunks: AsyncIterable<ChatChunk>): AsyncGenerator<string, void, void>;
+export declare function chatChunksToSseStream(chunks: AsyncIterable<ChatChunk>, onCancel?: () => void): ReadableStream<Uint8Array>;
+export declare function chatChunksToSseResponse(chunks: AsyncIterable<ChatChunk>): Response;
+/** Browser-side reader for the native wire format. Throws {@link OpenGeniChatError} on `event: error`. */
+export declare function parseChatChunkStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<ChatChunk, void, void>;

package/dist/chat/http.d.ts

@@ -0,0 +1,67 @@
+import type { OpenGeni } from "./opengeni.js";
+import { type ChatImportedMessage, type ChatOptions } from "./types.js";
+/** 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 declare const CHAT_CONVERSATION_HEADER = "x-opengeni-conversation";
+/** 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 declare function jsonResponse(body: unknown, status?: number, headers?: HeadersInit): Response;
+export declare function errorResponse(status: number, message: string, code: string): Response;
+export declare function readJsonObject(request: Request): Promise<Record<string, unknown> | null>;
+export declare function resolveChatRequest(request: Request, resolve: ChatResolve): Promise<{
+    resolution: ChatResolution;
+    response?: undefined;
+} | {
+    response: Response;
+}>;
+/** The client-supplied conversation: the header, else the protocol's own field. */
+export declare function clientConversation(request: Request, protocolField: unknown): string | 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 declare function openResolvedChat(og: OpenGeni, resolution: ChatResolution, clientConversationId: string | undefined): Promise<{
+    chat: Awaited<ReturnType<OpenGeni["chat"]>>;
+    response?: undefined;
+} | {
+    response: Response;
+}>;
+export declare function chatErrorSummary(error: unknown): ChatErrorSummary;
+export declare function sseHeaders(extra?: Record<string, string>): Record<string, string>;
+export declare function sseLine(data: string, event?: string): string;
+/**
+ * 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 declare function sseByteStream(blocks: AsyncIterable<string>, onCancel?: () => void): ReadableStream<Uint8Array>;
+/** Text from an OpenAI-style message content: a string or `[{ type, text }]` parts. */
+export declare function messageContentText(content: unknown, partTypes: string[]): string | null;
+/** The last user-role message's text from an OpenAI/Vercel-style `messages` array. */
+export declare function lastUserMessageText(messages: unknown, partTypes: string[], partsField: "parts" | "content"): string | null;
+/**
+ * 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 declare function importedHistoryBefore(messages: unknown, partTypes: string[], partsField: "parts" | "content"): ChatImportedMessage[];
+export declare function unixSeconds(): number;

package/dist/chat/ids.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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. With an end-user label the conversation id is
+ * namespaced to that user, so one user cannot address another user's
+ * conversation by guessing its id.
+ */
+/** 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 declare const CHAT_SESSION_NAMESPACE = "7c1e6d3a-5b2f-4e8a-9d4c-0f3b6a8e2c17";
+/** RFC 4122 version 5 (SHA-1) UUID of `name` inside `namespace`. */
+export declare function uuidV5(name: string, namespace: string): Promise<string>;
+/**
+ * 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 declare function chatSessionId(workspaceId: string, conversation: string, user?: ChatUserLabel | undefined): Promise<string>;
+/** The exact v5 name behind {@link chatSessionId}; exported for tests and audits. */
+export declare function chatIdentityName(workspaceId: string, conversation: string, user?: ChatUserLabel | undefined): string;
+/**
+ * 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 declare function chatIdempotencyKey(sessionId: string): string;
+export declare function isUuid(value: string): boolean;

package/dist/chat/index.d.ts

@@ -0,0 +1,7 @@
+export { Chat, DEFAULT_CHAT_SOURCE, DEFAULT_OPENGENI_BASE_URL, OpenGeni } from "./opengeni.js";
+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 ChatToolStatus, type OpenGeniOptions, } from "./types.js";
+export { CHAT_SESSION_NAMESPACE, chatIdempotencyKey, chatIdentityName, chatSessionId, uuidV5, type ChatUserLabel, } from "./ids.js";
+export { ChatTurnFold, approvalPending, humanInputPending, type ChatFoldStep, type ChatTurnTerminal, } from "./fold.js";
+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.js";
+export { UI_MESSAGE_STREAM_HEADER, UI_MESSAGE_STREAM_VERSION, chatChunksToUIMessageStream, handleVercelChatRequest, lastUIMessageText, uiMessageStreamBlocks, uiMessageStreamParts, uiMessageStreamResponse, type UIMessageStreamOptions, } from "./vercel.js";
+export { chatCompletionBlocks, chatCompletionObject, decodeResponseId, encodeResponseId, handleChatCompletionsRequest, handleResponsesRequest, responsesBlocks, responsesInputText, } from "./openai.js";