@opengeni/sdk 0.52.1 → 1.0.0

package/dist/chat/types.d.ts

@@ -0,0 +1,207 @@
+import type { FetchLike } from "../client.js";
+import type { Chats } from "../chats.js";
+import type { WorkspaceIdResolverOptions } from "../tenant-workspaces.js";
+import type { CreateSessionRequest, AgentConfigRequest, HumanInputAnswer, LatencyMode, ReasoningEffort, SessionEvent, Session, SessionSkill, ToolRef } from "../types.js";
+/** Which other sessions the agent may reach from this one. */
+export type ChatAgentAccess = "session" | "user" | "workspace";
+/**
+ * Compatibility option for personal or workspace Knowledge. `false` initializes
+ * Knowledge authoring to Off; authorized retrieval remains available. Omitted
+ * follows `chats`: private with a user, or legacy reach-based defaults without one.
+ * Task notes cover temporary session-tree data.
+ */
+export type ChatMemory = "user" | "workspace" | false;
+export type OpenGeniOptions = {
+    /** Organization API key. Keep it on the server. */
+    apiKey: string;
+    /**
+     * The organization (account) id that owns every workspace. Optional: when
+     * omitted it is read once from the API key.
+     */
+    organizationId?: string | undefined;
+    /** Defaults to `https://app.opengeni.ai`. */
+    baseUrl?: string | undefined;
+    /**
+     * The product identity used as the external-source label for tenant
+     * workspaces and end users. Defaults to `"app"`.
+     */
+    source?: string | undefined;
+    fetch?: FetchLike | undefined;
+    /** Display name for a tenant workspace created on first use. Defaults to the tenant id. */
+    workspaceName?: ((tenant: string) => string) | undefined;
+    /**
+     * Per-user workspaces only (`{ user }` alone, or `chats: "isolated"`):
+     * permissions for the one owner the SDK adds explicitly. Tenant workspaces
+     * rely on Opengeni, which adds a user on their first request. Both default
+     * to workspace read, session create/read/control (including sending
+     * messages), file upload/read, and per-session MCP attachment; no admin
+     * permissions. Never updates an existing membership: use
+     * `client.updateExternalWorkspaceMember` for that.
+     */
+    memberPermissions?: WorkspaceIdResolverOptions["memberPermissions"];
+};
+/**
+ * Which workspace, in your own ids: `tenant` (one workspace per tenant),
+ * neither (the `user`'s own workspace), or an explicit `workspaceId`.
+ */
+export type ChatTarget = {
+    tenant: string;
+    workspaceId?: undefined;
+} | {
+    workspaceId: string;
+    tenant?: undefined;
+} | {
+    user: string;
+    tenant?: undefined;
+    workspaceId?: undefined;
+};
+/**
+ * A workspace in your own ids, for `og.workspaceId(...)`: `{ tenant }` (one
+ * workspace per tenant), `{ user }` (one workspace per user), or
+ * `{ workspaceId }`. Precedence: workspaceId, then tenant, then user.
+ */
+export type WorkspaceTarget = {
+    tenant?: string | undefined;
+    user?: string | undefined;
+    workspaceId?: string | undefined;
+};
+export type ChatOptions = ChatTarget & {
+    /**
+     * Host-authenticated external user; resolved through server-side asUser().
+     * Without a tenant or workspaceId, the user gets one workspace of their own.
+     */
+    user?: string | undefined;
+    /** Stable conversation id; the session id is derived from it deterministically. */
+    conversation: string;
+    /** Prefer the actual OpenGeni session ID for shared or existing conversations.
+     * The acting user is independent of the conversation's identity. */
+    sessionId?: string | undefined;
+    /**
+     * Private (default with a user) uses personal Knowledge and session-only reach;
+     * shared uses workspace Knowledge/reach, isolated adds a workspace per tenant/user.
+     * Without a user, omission keeps workspace visibility, session reach and Knowledge off.
+     */
+    chats?: Chats | undefined;
+    /** Agent identity, capabilities and instructions; implicit markdown falls back on older servers. */
+    agent?: AgentConfigRequest | undefined;
+    /** Explicit agent reach overrides the `chats` default. */
+    agentAccess?: ChatAgentAccess | undefined;
+    memory?: ChatMemory | undefined;
+    model?: string | undefined;
+    instructions?: string | undefined;
+    skills?: SessionSkill[] | undefined;
+    tools?: ToolRef[] | undefined;
+    /**
+     * Raw create-request passthrough (for example `sandboxBackend: "none"` for a
+     * pure chat). Explicit values win over facade-derived ones; the message and
+     * identity/idempotency fields always come from the facade.
+     */
+    create?: Partial<CreateSessionRequest> | undefined;
+};
+/** A turn stopped to wait for a human decision. */
+export type ChatPending = {
+    kind: "approval" | "human_input";
+    /** The id to pass back through `chat.respond`. */
+    requestId: string;
+    /** Tool name for an approval; null for structured human input. */
+    name: string | null;
+    /** The producer's exact payload (approval entry or human-input request). */
+    payload: unknown;
+};
+export type ChatReplyStatus = "completed" | "pending" | "cancelled";
+export type ChatReply = {
+    text: string;
+    sessionId: string;
+    workspaceId: string;
+    turnId: string | null;
+    /** `pending` waits on `chat.respond`; `cancelled` carries the text produced before the cancel. */
+    status: ChatReplyStatus;
+    /** Set when the turn is waiting on `chat.respond` instead of finished. */
+    pending: ChatPending | null;
+    /** A non-destructive completion without a model-authored final answer. */
+    emptyFinalReply?: true;
+    /** Display this informational notice when emptyFinalReply is present. */
+    notice?: string;
+    /** Every event consumed while folding this turn. */
+    events: SessionEvent[];
+    toString(): string;
+};
+export type ChatToolStatus = "started" | "completed" | "failed";
+export type ChatChunk = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool";
+    name: string;
+    status: ChatToolStatus;
+    callId?: string | undefined;
+    input?: unknown;
+} | {
+    type: "pending";
+    pending: ChatPending;
+} | {
+    type: "done";
+    reply: ChatReply;
+};
+export type ChatMessage = {
+    role: "user" | "assistant";
+    text: string;
+    sequence: number;
+};
+/** Durable text and unresolved decisions restored when a chat is reopened. */
+export type ChatSnapshot = {
+    messages: ChatMessage[];
+    pending: ChatPending[];
+    status: Session["status"] | null;
+};
+export type ChatRespondInput = {
+    requestId: string;
+    decision: "approve" | "reject";
+    message?: string | undefined;
+} | {
+    requestId: string;
+    answers: HumanInputAnswer[];
+} | {
+    requestId: string;
+    skip: true;
+};
+/** One earlier message from the product's own history, imported as context on the first send. */
+export type ChatImportedMessage = {
+    role: "user" | "assistant" | "system";
+    text: string;
+};
+export type ChatSendOptions = {
+    signal?: AbortSignal | undefined;
+    /** Supersede the current inference instead of queueing behind it. */
+    steer?: boolean | undefined;
+    /**
+     * Earlier messages the product already holds, oldest first. Used only when
+     * this send creates the session: they become the first message's
+     * `modelContext` (skipped when `create.modelContext` was supplied), trimmed
+     * from the oldest end to 30,000 characters. Never resent on later turns:
+     * after the first message OpenGeni owns the history.
+     */
+    importedHistory?: ChatImportedMessage[] | undefined;
+    /** Model for this message's turn; omitted keeps the session's current policy. */
+    model?: string | undefined;
+    reasoningEffort?: ReasoningEffort | undefined;
+    latencyMode?: LatencyMode | undefined;
+    /**
+     * Model-visible application context for this one message (for example the
+     * page or record the user is looking at). Not shown in the transcript and not
+     * secret. On the creating message it is combined with imported history.
+     */
+    modelContext?: string | undefined;
+};
+export type ChatSessionListOptions = ChatTarget & {
+    user?: string | undefined;
+    /** Match the chat's mode; isolated lists that user's separate workspace. */
+    chats?: Chats | undefined;
+    limit?: number | undefined;
+};
+/** A turn ended without a usable reply, or the facade was misused. */
+export declare class OpenGeniChatError extends Error {
+    readonly code: string;
+    readonly event: SessionEvent | null;
+    constructor(code: string, message: string, event?: SessionEvent | null);
+}

package/dist/chat/vercel.d.ts

@@ -0,0 +1,49 @@
+import { type ChatResolve } from "./http.js";
+import type { OpenGeni } from "./opengeni.js";
+import type { ChatChunk } from "./types.js";
+/**
+ * Vercel AI SDK UI message stream (protocol v1, as consumed by `useChat` with
+ * the default transport in AI SDK 5, 6, and 7; approval requests need 6+).
+ * Parts are `data: <json>` SSE
+ * lines terminated by `data: [DONE]`, under the
+ * `x-vercel-ai-ui-message-stream: v1` header.
+ */
+export declare const UI_MESSAGE_STREAM_HEADER = "x-vercel-ai-ui-message-stream";
+export declare const UI_MESSAGE_STREAM_VERSION = "v1";
+export type UIMessageStreamOptions = {
+    /** Assistant message id announced in the `start` part. Defaults to a random UUID. */
+    messageId?: string | undefined;
+    /**
+     * Emit OpenGeni's own tool activity as tool parts. Off by default: those
+     * tools are not in the app's typed tool set. When on, parts are marked
+     * `dynamic` and `providerExecuted`, so `useChat` renders them as
+     * `dynamic-tool` parts and never tries to execute them. Approval requests
+     * are always emitted (as dynamic tool parts) because answering them is part
+     * of the conversation.
+     */
+    toolParts?: boolean | undefined;
+    /**
+     * Emit the `start` / `start-step` / `finish-step` / `finish` framing. Set to
+     * false when writing into an existing AI SDK stream that owns its framing
+     * (for example `createUIMessageStream({ execute: ({ writer }) => ... })`).
+     * Defaults to true.
+     */
+    framing?: boolean | undefined;
+};
+/** Protocol parts for one reply, in order. */
+export declare function uiMessageStreamParts(chunks: AsyncIterable<ChatChunk>, options?: UIMessageStreamOptions): AsyncGenerator<Record<string, unknown>, void, void>;
+export declare function uiMessageStreamBlocks(chunks: AsyncIterable<ChatChunk>, options?: UIMessageStreamOptions): AsyncGenerator<string, void, void>;
+export declare function chatChunksToUIMessageStream(chunks: AsyncIterable<ChatChunk>, options?: UIMessageStreamOptions & {
+    onCancel?: (() => void) | undefined;
+}): ReadableStream<Uint8Array>;
+export declare function uiMessageStreamResponse(chunks: AsyncIterable<ChatChunk>, options?: UIMessageStreamOptions): Response;
+/** Text of the last user `UIMessage` (`parts` of type `text`, joined). */
+export declare function lastUIMessageText(messages: unknown): string | null;
+/**
+ * `useChat` request handler: body `{ id, messages, trigger, messageId }`.
+ * Conversation: the host's `resolve`, else the `x-opengeni-conversation`
+ * header, else the chat `id`. Only the last user message is sent; the
+ * messages before it are imported once as context when this request creates
+ * the session. `regenerate-message` steers instead of queueing.
+ */
+export declare function handleVercelChatRequest(og: OpenGeni, request: Request, resolve: ChatResolve, options?: Pick<UIMessageStreamOptions, "toolParts">): Promise<Response>;

package/dist/chats.d.ts

@@ -0,0 +1,8 @@
+import type { CreateSessionRequest } from "./types.js";
+/**
+ * Private chats use personal Knowledge and session-only agent reach; shared chats
+ * use workspace Knowledge and reach. Isolated adds a separate workspace per user.
+ */
+export type Chats = "private" | "shared" | "isolated";
+/** SDK defaults only: the API still authorizes visibility, agent reach and Knowledge separately. */
+export declare function chatDefaults(chats: Chats): Required<Pick<CreateSessionRequest, "visibility" | "agentAccess" | "memoryScope">>;