@opengeni/sdk 0.57.0 → 1.0.0

package/src/retained-artifacts.ts

@@ -3,6 +3,7 @@ import type {
   GeneratedVideoReceipt,
   MediaGenerationResult,
   RetainedArtifactReference,
+  SandboxFileArtifactReceipt,
 } from "./types";
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -15,6 +16,94 @@ const MAX_VIDEO_BYTES = 512 * 1024 * 1024;
 const MAX_DIMENSION = 16_384;
 const MAX_PIXELS = 67_108_864;
 const MAX_RANGE_BYTES = 1024 * 1024;
+const MAX_SANDBOX_FILE_BYTES = 25 * 1024 * 1024 - 1;
+
+/** Zero-dependency validation for a permanent generic workspace-file receipt. */
+export function parseRetainedWorkspaceFileReference(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): RetainedArtifactReference | null {
+  if (!recordWithKeys(value, WORKSPACE_FILE_REFERENCE_KEYS)) return null;
+  const artifact = value as Record<string, unknown>;
+  if (
+    artifact.available !== true ||
+    artifact.kind !== "file" ||
+    typeof artifact.artifactId !== "string" ||
+    !UUID.test(artifact.artifactId) ||
+    typeof artifact.contentType !== "string" ||
+    !/^[a-z0-9][a-z0-9!#$&^_.+-]{0,62}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,62}$/.test(
+      artifact.contentType,
+    ) ||
+    !safeIntegerBetween(artifact.originalBytes, 1, MAX_SANDBOX_FILE_BYTES) ||
+    typeof artifact.sha256 !== "string" ||
+    !SHA256.test(artifact.sha256) ||
+    typeof artifact.retainedAt !== "string" ||
+    artifact.retainedAt.length > 64 ||
+    !ISO_DATETIME_WITH_OFFSET.test(artifact.retainedAt) ||
+    !Number.isFinite(Date.parse(artifact.retainedAt)) ||
+    !recordWithKeys(artifact.retention, RETENTION_KEYS) ||
+    !recordWithKeys(artifact.retrieval, RETRIEVAL_KEYS)
+  ) {
+    return null;
+  }
+  const retention = artifact.retention as Record<string, unknown>;
+  if (retention.policy !== "workspace_file" || retention.expiresAt !== null) return null;
+  const retrieval = artifact.retrieval as Record<string, unknown>;
+  if (
+    retrieval.method !== "GET" ||
+    retrieval.acceptRanges !== "bytes" ||
+    retrieval.maxRangeBytes !== MAX_RANGE_BYTES ||
+    typeof retrieval.path !== "string" ||
+    retrieval.path.length > 256
+  ) {
+    return null;
+  }
+  const match = WORKSPACE_PATH.exec(retrieval.path);
+  if (
+    !match ||
+    !UUID.test(match[1] ?? "") ||
+    match[2] !== artifact.artifactId ||
+    (expectedWorkspaceId !== undefined && match[1] !== expectedWorkspaceId)
+  ) {
+    return null;
+  }
+  return value as RetainedArtifactReference;
+}
+
+/** Parse the closed result returned by sandbox_file_publish and the session API. */
+export function parseSandboxFileArtifactReceipt(
+  value: unknown,
+  expectedWorkspaceId?: string,
+): SandboxFileArtifactReceipt | null {
+  if (typeof value === "string" && value.length <= 8_192) {
+    try {
+      return parseSandboxFileArtifactReceipt(JSON.parse(value), expectedWorkspaceId);
+    } catch {
+      return null;
+    }
+  }
+  if (!recordWithKeys(value, SANDBOX_FILE_RECEIPT_KEYS)) return null;
+  const artifact = parseRetainedWorkspaceFileReference(value.artifact, expectedWorkspaceId);
+  const pathSegments = typeof value.sandboxPath === "string" ? value.sandboxPath.split("/") : [];
+  if (
+    value.type !== "sandbox_file" ||
+    typeof value.sandboxPath !== "string" ||
+    !value.sandboxPath.startsWith("/workspace/") ||
+    value.sandboxPath.length > 4_096 ||
+    value.sandboxPath.includes("\0") ||
+    pathSegments.some(
+      (segment, index) => index > 1 && (!segment || segment === "." || segment === ".."),
+    ) ||
+    typeof value.filename !== "string" ||
+    value.filename.length < 1 ||
+    value.filename.length > 1_024 ||
+    pathSegments.at(-1) !== value.filename ||
+    !artifact
+  ) {
+    return null;
+  }
+  return value as SandboxFileArtifactReceipt;
+}
 
 /** Zero-dependency validation for the SDK's permanent generated-image wire receipt. */
 export function parseRetainedGeneratedImageReference(
@@ -272,10 +361,22 @@ const GENERATED_IMAGE_REFERENCE_KEYS = new Set([
   "retention",
   "retrieval",
 ]);
+const WORKSPACE_FILE_REFERENCE_KEYS = new Set([
+  "available",
+  "artifactId",
+  "kind",
+  "contentType",
+  "originalBytes",
+  "sha256",
+  "retainedAt",
+  "retention",
+  "retrieval",
+]);
 const DIMENSION_KEYS = new Set(["width", "height"]);
 const RETENTION_KEYS = new Set(["policy", "expiresAt"]);
 const RETRIEVAL_KEYS = new Set(["method", "path", "acceptRanges", "maxRangeBytes"]);
 const GENERATED_IMAGE_RECEIPT_KEYS = new Set(["type", "artifact", "sandboxPath"]);
+const SANDBOX_FILE_RECEIPT_KEYS = new Set(["type", "sandboxPath", "filename", "artifact"]);
 const GENERATED_VIDEO_RECEIPT_KEYS = new Set([
   "type",
   "schemaVersion",

package/src/session-history-import.ts

@@ -0,0 +1,84 @@
+import type { OpenGeniClient } from "./client";
+import type {
+  AppendArchivedSessionEventsRequest,
+  AppendArchivedSessionEventsResponse,
+  ImportArchivedSessionRequest,
+  ImportArchivedSessionResponse,
+} from "@opengeni/contracts";
+
+export type {
+  ArchivedSessionImportEvent,
+  AppendArchivedSessionEventsRequest,
+  AppendArchivedSessionEventsResponse,
+  ImportArchivedSessionRequest,
+  ImportArchivedSessionResponse,
+  SessionImportedArchive,
+} from "@opengeni/contracts";
+
+type SessionHistoryImportClient = Pick<OpenGeniClient, "requestJson">;
+
+/**
+ * Server-only migration of a read-only archive, not model-facing conversation
+ * history. Use an asUser client to preserve the verified creator/owner. Persist
+ * importId and retry the exact request after an uncertain outcome.
+ * Requires sessions:create in the authenticated actor's permissions.
+ */
+export function importArchivedSession(
+  client: SessionHistoryImportClient,
+  workspaceId: string,
+  request: ImportArchivedSessionRequest,
+): Promise<ImportArchivedSessionResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports`,
+    request,
+  );
+}
+
+/**
+ * Append historical events at the acknowledged nextOffset. Retrying the exact
+ * batchId, offset and events replays its receipt; conflicting reuse returns 409.
+ * Each request accepts at most 100 events / 1 MiB, with 256 KiB per event.
+ * Requires sessions:control and the same authenticated importer.
+ */
+export function appendArchivedSessionEvents(
+  client: SessionHistoryImportClient,
+  workspaceId: string,
+  importId: string,
+  request: AppendArchivedSessionEventsRequest,
+): Promise<AppendArchivedSessionEventsResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/session-imports/${encodeURIComponent(importId)}/events`,
+    request,
+  );
+}
+
+/** Import through an existing external tenant mapping; this does not onboard it. */
+export function importExternalWorkspaceArchivedSession(
+  client: SessionHistoryImportClient,
+  source: string,
+  externalId: string,
+  request: ImportArchivedSessionRequest,
+): Promise<ImportArchivedSessionResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports`,
+    request,
+  );
+}
+
+/** Append to an archive through the same external tenant mapping and actor. */
+export function appendExternalWorkspaceArchivedSessionEvents(
+  client: SessionHistoryImportClient,
+  source: string,
+  externalId: string,
+  importId: string,
+  request: AppendArchivedSessionEventsRequest,
+): Promise<AppendArchivedSessionEventsResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/external/${encodeURIComponent(source)}/${encodeURIComponent(externalId)}/session-imports/${encodeURIComponent(importId)}/events`,
+    request,
+  );
+}

package/src/session-list-entries.ts

@@ -0,0 +1 @@
+export { sessionListEntry } from "@opengeni/contracts/session-list-entries";

package/src/session-message-search.ts

@@ -0,0 +1,47 @@
+/** Literal Unicode case-insensitive substring. Whitespace is significant. */
+export type SessionMessageSearchRequest = {
+  query: string;
+  sessionId?: string | undefined;
+  /** Workspace-only first hit per session; cannot combine with sessionId. */
+  groupBy?: "session" | undefined;
+  archiveStatus?: "active" | "archived" | "all" | undefined;
+  limit?: number | undefined;
+  cursor?: string | undefined;
+};
+
+export type SessionMessageSearchMatch = {
+  sessionId: string;
+  sessionTitle: string | null;
+  eventId: string;
+  sequence: number;
+  turnId: string | null;
+  role: "user" | "assistant";
+  messageId: string | null;
+  /** Zero-based UTF-16 offset in the complete visible message. */
+  messageMatchOffset: number;
+  /** Zero-based UTF-16 offsets in text; matchEnd is exclusive. */
+  snippet: { text: string; matchStart: number; matchEnd: number };
+};
+
+export type SessionMessageSearchResponse = {
+  matches: SessionMessageSearchMatch[];
+  nextCursor: string | null;
+  /** Empty advancing pages are valid. Continue until false. */
+  hasMore: boolean;
+  /** Cumulative distinct messages visited in this live traversal. */
+  scannedMessages: number;
+  /** Cumulative matching messages, or session representatives with groupBy=session. */
+  matchedMessageCount: number;
+  /** Cumulative occurrences, or session representatives with groupBy=session. */
+  matchedOccurrenceCount: number;
+  /** True only on exhaustion. Concurrent mutations require a fresh traversal. */
+  countIsExact: boolean;
+};
+
+/** Exact selected event reference from a search match; no payload fields are read. */
+export type SessionMessagePreviewReference = { eventId: string; sequence: number };
+
+/** A complete visible message, or an explicit over-12,000-UTF-16-unit result. */
+export type SessionMessagePreview =
+  | { status: "available"; text: string }
+  | { status: "unavailable" };

package/src/session-proxy-client.ts

@@ -0,0 +1,64 @@
+import type { OpenGeniEmbeddingClient } from "./embedding-client";
+import type { OpenGeniRequestOptions, FetchResponse } from "./client";
+import type { AccessGrant } from "./types";
+
+/** Maximum actual UTF-8 bytes forwarded for one embedded Site HTML response. */
+export const SESSION_PROXY_SITE_HTML_MAX_BYTES = 25 * 1024 * 1024;
+
+/** A streaming Site download exceeded the host proxy's actual-byte ceiling. */
+export class SessionProxySiteHtmlTooLargeError extends Error {
+  readonly code = "site_html_too_large";
+  readonly limitBytes = SESSION_PROXY_SITE_HTML_MAX_BYTES;
+
+  constructor() {
+    super(`Site HTML exceeds the ${SESSION_PROXY_SITE_HTML_MAX_BYTES}-byte proxy limit.`);
+    this.name = "SessionProxySiteHtmlTooLargeError";
+  }
+}
+
+/** Server-only effective grant read; never derive external authority from access/me snapshots. */
+export function getSessionProxyWorkspaceGrant(
+  client: Pick<OpenGeniEmbeddingClient, "requestJson">,
+  workspaceId: string,
+  options: OpenGeniRequestOptions = {},
+): Promise<AccessGrant> {
+  return client.requestJson(
+    "GET",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/access/grant`,
+    undefined,
+    {},
+    options,
+  );
+}
+
+/** Exact association read. The API reauthorizes the source session on every call. */
+export function getSessionProxyArtifactAssociation(
+  client: Pick<OpenGeniEmbeddingClient, "requestJson">,
+  workspaceId: string,
+  sessionId: string,
+  kind: "editable" | "site",
+  artifactId: string,
+  options: OpenGeniRequestOptions = {},
+): Promise<{ sessionId: string; artifactId: string; kind: "editable" | "site" }> {
+  return client.requestJson(
+    "GET",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/sessions/${encodeURIComponent(sessionId)}/artifact-associations/${encodeURIComponent(artifactId)}`,
+    undefined,
+    { kind },
+    options,
+  );
+}
+
+/** Authenticated response stream for the server proxy; does not buffer Site HTML. */
+export function downloadSessionProxySiteHtml(
+  client: Pick<OpenGeniEmbeddingClient, "requestJsonResponse">,
+  workspaceId: string,
+  artifactId: string,
+  options: { versionId: string; signal?: AbortSignal },
+): Promise<FetchResponse> {
+  return client.requestJsonResponse(
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/published-artifacts/${encodeURIComponent(artifactId)}/html`,
+    { versionId: options.versionId },
+    options,
+  );
+}