@opengeni/sdk 0.57.0 → 1.0.0

package/src/adapters/express.ts

@@ -0,0 +1,136 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+
+/** Any web-standard handler: `createSessionProxyHandler`, `createChatHandler`, or your own. */
+export type WebHandler = (request: Request) => Promise<Response>;
+
+/** Express/Connect request: Node's `IncomingMessage` plus what those frameworks add. */
+export type NodeRequestLike = IncomingMessage & {
+  originalUrl?: string | undefined;
+  /** Set when a body parser (for example `express.json()`) already consumed the body. */
+  body?: unknown;
+  protocol?: string | undefined;
+};
+
+export type NodeMiddleware = (
+  request: NodeRequestLike,
+  response: ServerResponse,
+  next?: (error?: unknown) => void,
+) => void;
+
+export type NodeMiddlewareOptions = {
+  /** Origin used to build the request URL. Defaults to the Host header over http(s). */
+  origin?: string | undefined;
+};
+
+/**
+ * Expose a web-standard handler as Express/Connect (or plain `node:http`)
+ * middleware. Mount it with the same path the browser client uses:
+ *
+ * ```ts
+ * app.use("/api/opengeni", toNodeMiddleware(handler));
+ * ```
+ *
+ * The full original URL is forwarded (Express strips the mount path from
+ * `req.url`), bodies stream through unless a body parser already consumed
+ * them, responses (including SSE) are written as they arrive, and a client
+ * disconnect aborts the request signal.
+ */
+export function toNodeMiddleware(
+  handler: WebHandler,
+  options: NodeMiddlewareOptions = {},
+): NodeMiddleware {
+  return (request, response, next) => {
+    void (async () => {
+      const abort = new AbortController();
+      response.once("close", () => {
+        if (!response.writableFinished) abort.abort();
+      });
+      const web = await handler(toWebRequest(request, abort.signal, options));
+      await writeWebResponse(web, response);
+    })().catch((error: unknown) => {
+      if (next) next(error);
+      else if (!response.headersSent) {
+        response.statusCode = 500;
+        response.end();
+      } else response.destroy(error instanceof Error ? error : undefined);
+    });
+  };
+}
+
+/** Express/Connect naming alias. */
+export const toExpressMiddleware = toNodeMiddleware;
+
+function toWebRequest(
+  request: NodeRequestLike,
+  signal: AbortSignal,
+  options: NodeMiddlewareOptions,
+): Request {
+  const encrypted = (request.socket as { encrypted?: boolean } | undefined)?.encrypted === true;
+  const origin =
+    options.origin?.replace(/\/+$/, "") ??
+    `${request.protocol ?? (encrypted ? "https" : "http")}://${request.headers.host ?? "localhost"}`;
+  const url = new URL(request.originalUrl ?? request.url ?? "/", origin);
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(request.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) for (const item of value) headers.append(name, item);
+    else headers.set(name, value);
+  }
+  const method = request.method ?? "GET";
+  let body: BodyInit | undefined;
+  if (method !== "GET" && method !== "HEAD") {
+    if (request.body !== undefined && (request.readableEnded || request.complete)) {
+      // A body parser consumed the stream: forward what it parsed.
+      body =
+        typeof request.body === "string" || request.body instanceof Uint8Array
+          ? (request.body as string | Uint8Array<ArrayBuffer>)
+          : JSON.stringify(request.body);
+      headers.delete("content-length");
+    } else {
+      body = Readable.toWeb(request) as unknown as ReadableStream<Uint8Array>;
+    }
+  }
+  return new Request(url, {
+    method,
+    headers,
+    signal,
+    ...(body !== undefined ? { body, duplex: "half" } : {}),
+  } as RequestInit);
+}
+
+async function writeWebResponse(web: Response, response: ServerResponse): Promise<void> {
+  response.statusCode = web.status;
+  const cookies = web.headers.getSetCookie?.() ?? [];
+  web.headers.forEach((value, name) => {
+    if (name.toLowerCase() !== "set-cookie") response.setHeader(name, value);
+  });
+  if (cookies.length > 0) response.setHeader("set-cookie", cookies);
+  if (!web.body) {
+    response.end();
+    return;
+  }
+  // Send headers now so SSE clients see the stream open before the first event.
+  response.flushHeaders();
+  const reader = web.body.getReader();
+  response.once("close", () => {
+    void reader.cancel().catch(() => undefined);
+  });
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!response.write(value)) {
+      await new Promise<void>((resolve) => {
+        const settle = () => {
+          response.off("drain", settle);
+          response.off("close", settle);
+          resolve();
+        };
+        response.once("drain", settle);
+        response.once("close", settle);
+      });
+    }
+    if (response.destroyed) break;
+  }
+  response.end();
+}

package/src/adapters/hono.ts

@@ -0,0 +1,18 @@
+/** Any web-standard handler: `createSessionProxyHandler`, `createChatHandler`, or your own. */
+export type WebHandler = (request: Request) => Promise<Response>;
+
+/** The part of Hono's context this adapter uses (no Hono dependency). */
+export type HonoContextLike = { req: { raw: Request } };
+
+/**
+ * Expose a web-standard handler as a Hono handler:
+ *
+ * ```ts
+ * app.all("/api/opengeni/*", toHonoHandler(handler));
+ * ```
+ */
+export function toHonoHandler(
+  handler: WebHandler,
+): (context: HonoContextLike) => Promise<Response> {
+  return async (context) => await handler(context.req.raw);
+}

package/src/adapters/next.ts

@@ -0,0 +1,42 @@
+import { createSessionProxyHandler, type SessionProxyHandlerOptions } from "../session-proxy";
+
+/** Any web-standard handler: `createSessionProxyHandler`, `createChatHandler`, or your own. */
+export type WebHandler = (request: Request) => Promise<Response>;
+
+/** Route handlers for a Next.js App Router catch-all route. */
+export type NextRouteHandlers = {
+  GET: WebHandler;
+  POST: WebHandler;
+  PUT: WebHandler;
+  PATCH: WebHandler;
+  DELETE: WebHandler;
+};
+
+/**
+ * Expose a web-standard handler as Next.js App Router route handlers.
+ *
+ * ```ts
+ * // app/api/opengeni/[...path]/route.ts
+ * export const dynamic = "force-dynamic";
+ * export const { GET, POST, PUT, PATCH, DELETE } = toNextRouteHandlers(handler);
+ * ```
+ *
+ * Next passes the full request URL (including any `basePath`), so the proxy's
+ * own `/v1/` detection routes it; responses, including SSE, stream as-is.
+ */
+export function toNextRouteHandlers(handler: WebHandler): NextRouteHandlers {
+  // Next calls route handlers with (request, context); only the request matters.
+  const route: WebHandler = async (request) => await handler(request);
+  return { GET: route, POST: route, PUT: route, PATCH: route, DELETE: route };
+}
+
+/**
+ * `createSessionProxyHandler` as Next.js App Router route handlers, for
+ * `app/<mount>/[...path]/route.ts`.
+ */
+export function createSessionProxyRoute(
+  target: Parameters<typeof createSessionProxyHandler>[0],
+  options: SessionProxyHandlerOptions,
+): NextRouteHandlers {
+  return toNextRouteHandlers(createSessionProxyHandler(target, options));
+}

package/src/allowance-refusal.ts

@@ -0,0 +1,5 @@
+/** Browser-safe allowance presentation without exposing the server core. */
+export {
+  allowanceExhaustedMessage,
+  parseAllowanceExhaustedRefusal,
+} from "@opengeni/contracts/allowance-refusal";

package/src/artifact-catalog.ts

@@ -0,0 +1,41 @@
+import type { RetainedArtifactReference } from "./types";
+
+export type ArtifactCatalogKind =
+  | "site"
+  | "document"
+  | "spreadsheet"
+  | "presentation"
+  | "image"
+  | "file";
+
+/** Native IDs are unique within a kind; use `${kind}:${id}` as a UI key. */
+export type ArtifactCatalogItem = {
+  id: string;
+  kind: ArtifactCatalogKind;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+  status: "active" | "archived";
+  /** Present only when the viewer can read this session. */
+  sourceSessionId?: string;
+  versionId?: string;
+  file?: RetainedArtifactReference;
+  filename?: string;
+  contentType?: string;
+  sizeBytes?: number;
+};
+
+export type ArtifactCatalogListOptions = {
+  sourceSessionId?: string;
+  q?: string;
+  kind?: ArtifactCatalogKind;
+  sort?: "updated" | "newest" | "title";
+  status?: "active" | "archived";
+  limit?: number;
+  cursor?: string;
+};
+
+export type ArtifactCatalogListResponse = {
+  items: ArtifactCatalogItem[];
+  nextCursor: string | null;
+};

package/src/artifact-client.ts

@@ -1,4 +1,13 @@
-import { OpenGeniClient as OpenGeniCoreClient } from "./client";
+import { OpenGeniDocumentAuthorityClient } from "./document-authority-client";
+import type { FetchResponse } from "./client";
+import type { SiteToolCallRequest } from "./site-tool-bridge";
+import type { ToolGatewayCallResponse } from "./types";
+import type {
+  CreateWorkspaceArtifactRequest,
+  PublishWorkspaceArtifactVersionRequest,
+  WorkspaceArtifactContentResponse,
+  WorkspaceArtifactMutationResponse,
+} from "./workspace-artifacts";
 import type {
   CreateEditableArtifactMaterializationRequest,
   CreateEditableArtifactResourceRequest,
@@ -12,19 +21,9 @@ import type {
   ReadEditableArtifactMaterializationOptions,
   ReadEditableArtifactResourceOptions,
 } from "./editable-artifact-resources";
-import type {
-  CreateWorkspaceArtifactRequest,
-  PublishWorkspaceArtifactVersionRequest,
-  RollbackWorkspaceArtifactRequest,
-  WorkspaceArtifactContentResponse,
-  WorkspaceArtifactDetailResponse,
-  WorkspaceArtifactListOptions,
-  WorkspaceArtifactListResponse,
-  WorkspaceArtifactMutationResponse,
-} from "./workspace-artifacts";
 
-/** Public SDK client. Artifact operations stay out of the console's eager core graph. */
-export class OpenGeniClient extends OpenGeniCoreClient {
+/** Public SDK client. Optional operator and artifact operations stay out of the console core. */
+export class OpenGeniClient extends OpenGeniDocumentAuthorityClient {
   async createEditableArtifact(
     workspaceId: string,
     request: CreateEditableArtifactResourceRequest,
@@ -132,7 +131,7 @@ export class OpenGeniClient extends OpenGeniCoreClient {
     artifactId: string,
     jobId: string,
     options: ReadEditableArtifactMaterializationOptions,
-  ): Promise<Response> {
+  ): Promise<FetchResponse> {
     return await this.requestResponse(
       "GET",
       `/v1/workspaces/${encodeURIComponent(workspaceId)}/editable-artifacts/${encodeURIComponent(artifactId)}/materializations/${encodeURIComponent(jobId)}/download`,
@@ -140,51 +139,52 @@ export class OpenGeniClient extends OpenGeniCoreClient {
       options,
     );
   }
-
-  async listWorkspaceArtifacts(
-    workspaceId: string,
-    options: WorkspaceArtifactListOptions = {},
-  ): Promise<WorkspaceArtifactListResponse> {
-    const query = new URLSearchParams();
-    if (options.limit !== undefined) query.set("limit", String(options.limit));
-    if (options.cursor) query.set("cursor", options.cursor);
-    const suffix = query.size > 0 ? `?${query.toString()}` : "";
-    return await this.requestJson<WorkspaceArtifactListResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/published-artifacts${suffix}`,
-    );
-  }
-
-  async getWorkspaceArtifact(
+  /** Exact Site-version gateway call. Keep this client on the authenticated host;
+   * the API enforces live viewer access and the version's declared tool allowlist. */
+  async callWorkspaceSiteTool(
     workspaceId: string,
-    artifactId: string,
-  ): Promise<WorkspaceArtifactDetailResponse> {
-    return await this.requestJson<WorkspaceArtifactDetailResponse>(
-      "GET",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}`,
+    request: SiteToolCallRequest,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<ToolGatewayCallResponse> {
+    return this.requestJson<ToolGatewayCallResponse>(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/tools/calls`,
+      request,
+      undefined,
+      options,
     );
   }
 
   async getWorkspaceArtifactContent(
     workspaceId: string,
     artifactId: string,
-    versionId?: string,
+    versionOrOptions?: string | { versionId?: string; signal?: AbortSignal },
   ): Promise<WorkspaceArtifactContentResponse> {
-    const query = versionId ? `?versionId=${encodeURIComponent(versionId)}` : "";
+    const options =
+      typeof versionOrOptions === "string"
+        ? { versionId: versionOrOptions }
+        : (versionOrOptions ?? {});
+    const query = options.versionId ? `?versionId=${encodeURIComponent(options.versionId)}` : "";
     return await this.requestJson<WorkspaceArtifactContentResponse>(
       "GET",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}/content${query}`,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts/${encodeURIComponent(artifactId)}/content${query}`,
+      undefined,
+      undefined,
+      options,
     );
   }
 
   async createWorkspaceArtifact(
     workspaceId: string,
     request: CreateWorkspaceArtifactRequest,
+    options: { signal?: AbortSignal } = {},
   ): Promise<WorkspaceArtifactMutationResponse> {
     return await this.requestJson<WorkspaceArtifactMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/published-artifacts`,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts`,
       request,
+      undefined,
+      options,
     );
   }
 
@@ -192,23 +192,14 @@ export class OpenGeniClient extends OpenGeniCoreClient {
     workspaceId: string,
     artifactId: string,
     request: PublishWorkspaceArtifactVersionRequest,
+    options: { signal?: AbortSignal } = {},
   ): Promise<WorkspaceArtifactMutationResponse> {
     return await this.requestJson<WorkspaceArtifactMutationResponse>(
       "POST",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}/versions`,
-      request,
-    );
-  }
-
-  async rollbackWorkspaceArtifact(
-    workspaceId: string,
-    artifactId: string,
-    request: RollbackWorkspaceArtifactRequest,
-  ): Promise<WorkspaceArtifactMutationResponse> {
-    return await this.requestJson<WorkspaceArtifactMutationResponse>(
-      "POST",
-      `/v1/workspaces/${workspaceId}/published-artifacts/${encodeURIComponent(artifactId)}/rollback`,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts/${encodeURIComponent(artifactId)}/versions`,
       request,
+      undefined,
+      options,
     );
   }
 }

package/src/artifacts.ts

@@ -14,4 +14,10 @@ export type {
   ReadEditableArtifactMaterializationOptions,
   ReadEditableArtifactResourceOptions,
 } from "./editable-artifact-resources";
-export type { FetchLike, OpenGeniClientOptions, OpenGeniRequestOptions } from "./client";
+export type {
+  FetchLike,
+  FetchResponse,
+  GetSessionOptions,
+  OpenGeniClientOptions,
+  OpenGeniRequestOptions,
+} from "./client";

package/src/automations-client.ts

@@ -0,0 +1,124 @@
+import type {
+  AutomationRun,
+  AutomationSource,
+  AutomationTrigger,
+  AutomationWebhookResult,
+  CreateAutomationSourceRequest,
+  CreateAutomationTriggerRequest,
+  TriggerAutomationManuallyRequest,
+  UpdateAutomationSourceRequest,
+  UpdateAutomationTriggerRequest,
+} from "@opengeni/contracts";
+import type { OpenGeniClient as OpenGeniCoreClient } from "./client";
+
+export type OpenGeniAutomationsTransport = Pick<OpenGeniCoreClient, "requestJson">;
+
+export class OpenGeniAutomationsClient {
+  constructor(private readonly client: OpenGeniAutomationsTransport) {}
+
+  async listSources(workspaceId: string): Promise<AutomationSource[]> {
+    const result = await this.client.requestJson<{ sources: AutomationSource[] }>(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources`,
+    );
+    return result.sources;
+  }
+
+  async createSource(
+    workspaceId: string,
+    request: CreateAutomationSourceRequest,
+  ): Promise<AutomationSource> {
+    return await this.client.requestJson(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources`,
+      request,
+    );
+  }
+
+  async updateSource(
+    workspaceId: string,
+    sourceId: string,
+    request: UpdateAutomationSourceRequest,
+  ): Promise<AutomationSource> {
+    return await this.client.requestJson(
+      "PATCH",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}`,
+      request,
+    );
+  }
+
+  async disableSource(workspaceId: string, sourceId: string): Promise<void> {
+    await this.client.requestJson<void>(
+      "DELETE",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}`,
+      undefined,
+      {},
+      { responseType: "void" },
+    );
+  }
+
+  async listTriggers(workspaceId: string): Promise<AutomationTrigger[]> {
+    const result = await this.client.requestJson<{ triggers: AutomationTrigger[] }>(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers`,
+    );
+    return result.triggers;
+  }
+
+  async createTrigger(
+    workspaceId: string,
+    request: CreateAutomationTriggerRequest,
+  ): Promise<AutomationTrigger> {
+    return await this.client.requestJson(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers`,
+      request,
+    );
+  }
+
+  async updateTrigger(
+    workspaceId: string,
+    triggerId: string,
+    request: UpdateAutomationTriggerRequest,
+  ): Promise<AutomationTrigger> {
+    return await this.client.requestJson(
+      "PATCH",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers/${encodeURIComponent(triggerId)}`,
+      request,
+    );
+  }
+
+  async disableTrigger(
+    workspaceId: string,
+    triggerId: string,
+    expectedRevision: number,
+  ): Promise<void> {
+    await this.client.requestJson<void>(
+      "DELETE",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/triggers/${encodeURIComponent(triggerId)}?expectedRevision=${expectedRevision}`,
+      undefined,
+      {},
+      { responseType: "void" },
+    );
+  }
+
+  async listRuns(workspaceId: string): Promise<AutomationRun[]> {
+    const result = await this.client.requestJson<{ runs: AutomationRun[] }>(
+      "GET",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/runs`,
+    );
+    return result.runs;
+  }
+
+  async triggerManually(
+    workspaceId: string,
+    sourceId: string,
+    request: TriggerAutomationManuallyRequest,
+  ): Promise<AutomationWebhookResult> {
+    return await this.client.requestJson(
+      "POST",
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/automations/sources/${encodeURIComponent(sourceId)}/events`,
+      request,
+    );
+  }
+}

package/src/automations.ts

@@ -0,0 +1,15 @@
+export { OpenGeniAutomationsClient } from "./automations-client";
+export type { OpenGeniAutomationsTransport } from "./automations-client";
+export type {
+  AutomationAcceptedExecution,
+  AutomationNormalizedEvent,
+  AutomationRun,
+  AutomationSource,
+  AutomationTrigger,
+  AutomationWebhookResult,
+  CreateAutomationSourceRequest,
+  CreateAutomationTriggerRequest,
+  TriggerAutomationManuallyRequest,
+  UpdateAutomationSourceRequest,
+  UpdateAutomationTriggerRequest,
+} from "@opengeni/contracts";

package/src/browser.ts

@@ -0,0 +1,54 @@
+/** Browser-console client. Optional SDK surfaces must not enter this eager graph. */
+export { OpenGeniClient as OpenGeniBrowserClient } from "./client";
+export type {
+  SessionMessageSearchRequest,
+  SessionMessageSearchMatch,
+  SessionMessageSearchResponse,
+  SessionMessagePreview,
+  SessionMessagePreviewReference,
+} from "./session-message-search";
+export {
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  OpenGeniToolsClient,
+} from "./tools";
+export type {
+  OpenGeniGeneratedTools,
+  OpenGeniDynamicToolNode,
+  OpenGeniToolCallOptions,
+  OpenGeniToolFunction,
+  OpenGeniToolsFacade,
+  OpenGeniWorkspaceTools,
+} from "./tools";
+export type {
+  FetchLike,
+  FetchResponse,
+  GetSessionOptions,
+  OpenGeniClientOptions,
+  OpenGeniRequestOptions,
+  SendMessageInput,
+  SteerMessageResult,
+  TranscribeAudioInput,
+  WorkspaceControlEventPage,
+} from "./client";
+export {
+  OpenGeniApiContractMismatchError,
+  OpenGeniApiError,
+  OpenGeniSetupError,
+  OpenGeniAllowanceExhaustedError,
+  OpenGeniSecureContextRequiredError,
+  OpenGeniSessionListCursorError,
+  OpenGeniStreamError,
+  formatErrorMessage,
+  isRetryableStreamError,
+} from "./errors";
+export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
+export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";
+
+export type {
+  ConnectorToolPermission,
+  ConnectorToolPermissionEntry,
+  ConnectorToolPermissionsResponse,
+  UpdateConnectorToolPermissionsRequest,
+} from "./types";