@opengeni/sdk 0.29.0 → 0.33.1

package/src/client.ts

@@ -29,6 +29,8 @@ import type {
   CodexUsageMap,
   BillingSummary,
   BillingUsageResponse,
+  InsightsRange,
+  WorkspaceInsightsResponse,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
   CapabilityInstallation,
@@ -92,6 +94,7 @@ import type {
   SwapActiveSandboxResponse,
   ListWorkspaceMembersResponse,
   PackInstallation,
+  LatencyMode,
   ReasoningEffort,
   RetainedArtifactContent,
   RetainedArtifactContentOptions,
@@ -169,6 +172,7 @@ import type {
   PtyResizeRequest,
   PtyCloseRequest,
   ToolRef,
+  TranscribeAudioResponse,
   UpdateConnectionRequest,
   UpdateKnowledgeMemoryRequest,
   UpdateScheduledTaskRequest,
@@ -210,6 +214,23 @@ import type {
   WorkspaceInstructionPolicyListResponse,
   WorkspaceInstructionPolicyRevision,
 } from "./workspace-instruction-policies";
+import type { WorkspaceStateResponse } from "./workspace-state";
+import type {
+  ActivatePreferenceRegistryRevisionRequest,
+  ChangePreferenceRegistryScopeRequest,
+  CorrectPreferenceRegistryRequest,
+  CreatePreferenceRegistryProposalRequest,
+  DeactivatePreferenceRegistryRequest,
+  PreferenceRegistryDetailResponse,
+  PreferenceRegistryFullContent,
+  PreferenceRegistryListOptions,
+  PreferenceRegistryListResponse,
+  PreferenceRegistryMutationResponse,
+  PreferenceRegistryRecord,
+  PreferenceRegistrySnapshot,
+  RejectPreferenceRegistryProposalRequest,
+  SupersedePreferenceRegistryRequest,
+} from "./preference-registry";
 import {
   OPENGENI_API_CONTRACT_HEADER,
   OPENGENI_API_CONTRACT_REVISION,
@@ -248,7 +269,7 @@ export type OpenGeniClientOptions = {
   fetch?: FetchLike;
 };
 
-/** Per-request cancellation for identity-scoped, side-effect-free reads. */
+/** Per-request cancellation for operations whose caller owns an AbortSignal. */
 export type OpenGeniRequestOptions = {
   signal?: AbortSignal | undefined;
 };
@@ -261,6 +282,7 @@ export type SendMessageInput = {
   tools?: ToolRef[];
   model?: string;
   reasoningEffort?: ReasoningEffort;
+  latencyMode?: LatencyMode;
   clientEventId?: string;
   controlEtag?: string;
   expectedDraftRevision?: number;
@@ -274,6 +296,13 @@ export type SteerMessageResult = {
   turn: SessionTurn;
 };
 
+export type TranscribeAudioInput = {
+  audio: Blob | File | Uint8Array;
+  mimeType: string;
+  durationSeconds?: number | undefined;
+  signal?: AbortSignal | undefined;
+};
+
 /**
  * Typed client for the OpenGeni public API. Framework-agnostic: only needs
  * WHATWG `fetch` + streams, so it runs in Node 18+, Bun, Deno, browsers, and
@@ -293,6 +322,60 @@ export class OpenGeniClient {
 
   // --- Session lifecycle ---------------------------------------------------
 
+  /** Upload one ephemeral browser recording. This method never retries. */
+  async transcribeAudio(
+    workspaceId: string,
+    input: TranscribeAudioInput,
+  ): Promise<TranscribeAudioResponse> {
+    const correlationId = crypto.randomUUID();
+    const form = new FormData();
+    const filename = filenameForAudioMimeType(input.mimeType);
+    const audio =
+      input.audio instanceof File
+        ? input.audio
+        : input.audio instanceof Uint8Array
+          ? new File([Uint8Array.from(input.audio)], filename, { type: input.mimeType })
+          : new File([input.audio], filename, { type: input.mimeType || input.audio.type });
+    form.append("audio", audio, filename);
+    form.append("mimeType", input.mimeType);
+    if (input.durationSeconds !== undefined) {
+      form.append("durationSeconds", String(input.durationSeconds));
+    }
+    let response: Response;
+    try {
+      response = await this.fetchImpl(this.url(`/v1/workspaces/${workspaceId}/transcriptions`), {
+        method: "POST",
+        headers: { ...this.headers(correlationId), Accept: "application/json" },
+        body: form,
+        ...(input.signal ? { signal: input.signal } : {}),
+      });
+    } catch (error) {
+      if (input.signal?.aborted) throw error;
+      throw mutationTransportError(correlationId);
+    }
+    assertApiContractResponse(response);
+    if (!response.ok) throw await apiErrorFromResponse(response, { method: "POST", correlationId });
+    await assertJsonResponse(response, { method: "POST", correlationId });
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch {
+      throw new OpenGeniApiError(response.status, "Invalid transcription response.", {
+        code: "invalid_response",
+        mutation: true,
+        correlationId,
+      });
+    }
+    if (!isTranscribeAudioResponse(body)) {
+      throw new OpenGeniApiError(response.status, "Invalid transcription response.", {
+        code: "invalid_response",
+        mutation: true,
+        correlationId,
+      });
+    }
+    return body;
+  }
+
   async createSession(
     workspaceId: string,
     request: CreateSessionRequest,
@@ -482,7 +565,7 @@ export class OpenGeniClient {
   async listTurns(
     workspaceId: string,
     sessionId: string,
-    options: { limit?: number } = {},
+    options: { limit?: number; latestStarted?: boolean } = {},
   ): Promise<SessionTurn[]> {
     return await this.requestJson<SessionTurn[]>(
       "GET",
@@ -490,10 +573,17 @@ export class OpenGeniClient {
       undefined,
       {
         ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
+        ...(options.latestStarted ? { latestStarted: "1" } : {}),
       },
     );
   }
 
+  /** Newest turn that durably emitted `turn.started`, or null before any admission. */
+  async getLatestStartedTurn(workspaceId: string, sessionId: string): Promise<SessionTurn | null> {
+    const turns = await this.listTurns(workspaceId, sessionId, { latestStarted: true });
+    return turns[0] ?? null;
+  }
+
   // --- Bring-your-own-compute: Machines dashboard + metrics (M10) ------------
 
   /**
@@ -1623,6 +1713,14 @@ export class OpenGeniClient {
     return await this.requestJson<Workspace>("GET", `/v1/workspaces/${workspaceId}`);
   }
 
+  /** Read-time, secret-safe inventory of policy heads and visible workspace knowledge. */
+  async getWorkspaceState(workspaceId: string): Promise<WorkspaceStateResponse> {
+    return await this.requestJson<WorkspaceStateResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/workspace-state`,
+    );
+  }
+
   async updateWorkspace(workspaceId: string, request: UpdateWorkspaceRequest): Promise<Workspace> {
     return await this.requestJson<Workspace>("PATCH", `/v1/workspaces/${workspaceId}`, request);
   }
@@ -1717,6 +1815,132 @@ export class OpenGeniClient {
     );
   }
 
+  async listPreferenceRegistry(
+    workspaceId: string,
+    options: PreferenceRegistryListOptions = {},
+  ): Promise<PreferenceRegistryListResponse> {
+    const params = new URLSearchParams();
+    if (options.scope) params.set("scope", options.scope);
+    if (options.status) params.set("status", options.status);
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    const query = params.toString();
+    return await this.requestJson<PreferenceRegistryListResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences${query ? `?${query}` : ""}`,
+    );
+  }
+
+  async getPreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+  ): Promise<PreferenceRegistryDetailResponse> {
+    return await this.requestJson<PreferenceRegistryDetailResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}`,
+    );
+  }
+
+  async createPreferenceRegistryProposal(
+    workspaceId: string,
+    request: CreatePreferenceRegistryProposalRequest,
+  ): Promise<PreferenceRegistryRecord> {
+    return await this.requestJson<PreferenceRegistryRecord>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/proposals`,
+      request,
+    );
+  }
+
+  async activatePreferenceRegistryRevision(
+    workspaceId: string,
+    preferenceId: string,
+    request: ActivatePreferenceRegistryRevisionRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/activate`,
+      request,
+    );
+  }
+
+  async correctPreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: CorrectPreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/correct`,
+      request,
+    );
+  }
+
+  async changePreferenceRegistryScope(
+    workspaceId: string,
+    preferenceId: string,
+    request: ChangePreferenceRegistryScopeRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/scope`,
+      request,
+    );
+  }
+
+  async deactivatePreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: DeactivatePreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/deactivate`,
+      request,
+    );
+  }
+
+  async supersedePreferenceRegistry(
+    workspaceId: string,
+    preferenceId: string,
+    request: SupersedePreferenceRegistryRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/supersede`,
+      request,
+    );
+  }
+
+  async rejectPreferenceRegistryProposal(
+    workspaceId: string,
+    preferenceId: string,
+    request: RejectPreferenceRegistryProposalRequest,
+  ): Promise<PreferenceRegistryMutationResponse> {
+    return await this.requestJson<PreferenceRegistryMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/${encodeURIComponent(preferenceId)}/reject`,
+      request,
+    );
+  }
+
+  async getPreferenceRegistrySummary(workspaceId: string): Promise<PreferenceRegistrySnapshot> {
+    return await this.requestJson<PreferenceRegistrySnapshot>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/preferences/summary`,
+    );
+  }
+
+  async getPreferenceRegistryFullContent(
+    workspaceId: string,
+    retrievalHandle: string,
+  ): Promise<PreferenceRegistryFullContent> {
+    return await this.requestJson<PreferenceRegistryFullContent>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/preferences/full-content`,
+      { retrievalHandle },
+    );
+  }
+
   /**
    * Delete a workspace and everything in it. Refused (409) for the account's
    * only workspace and while it still has a running session. Irreversible.
@@ -2627,11 +2851,14 @@ export class OpenGeniClient {
   async startConnectionOAuth(
     workspaceId: string,
     request: OAuthStartRequest,
+    options: OpenGeniRequestOptions = {},
   ): Promise<OAuthStartResponse> {
     return await this.requestJson<OAuthStartResponse>(
       "POST",
       `/v1/workspaces/${workspaceId}/connections/oauth/start`,
       request,
+      {},
+      options,
     );
   }
 
@@ -2734,6 +2961,26 @@ export class OpenGeniClient {
     });
   }
 
+  async getWorkspaceInsights(
+    workspaceId: string,
+    options: {
+      range?: InsightsRange;
+      provider?: string;
+      model?: string;
+    } = {},
+  ): Promise<WorkspaceInsightsResponse> {
+    return await this.requestJson<WorkspaceInsightsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/insights`,
+      undefined,
+      {
+        range: options.range ?? "week",
+        ...(options.provider !== undefined ? { provider: options.provider } : {}),
+        ...(options.model !== undefined ? { model: options.model } : {}),
+      },
+    );
+  }
+
   async getBillingEntitlements(
     options: { accountId?: string } = {},
   ): Promise<BillingEntitlementsResponse> {
@@ -2918,7 +3165,7 @@ export class OpenGeniClient {
     );
   }
 
-  private async requestJson<T>(
+  protected async requestJson<T>(
     method: string,
     path: string,
     body?: unknown,
@@ -2993,6 +3240,36 @@ function assertApiContractResponse(response: Response): void {
   }
 }
 
+function isTranscribeAudioResponse(value: unknown): value is TranscribeAudioResponse {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    typeof record.text === "string" &&
+    Array.isArray(record.languages) &&
+    record.languages.every((language) => typeof language === "string")
+  );
+}
+
+function filenameForAudioMimeType(mimeType: string): string {
+  const bare = mimeType.trim().toLowerCase().split(";")[0] ?? "audio/webm";
+  switch (bare) {
+    case "audio/mp4":
+    case "audio/m4a":
+      return "audio.mp4";
+    case "audio/ogg":
+      return "audio.ogg";
+    case "audio/mpeg":
+    case "audio/mp3":
+      return "audio.mp3";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "audio.wav";
+    case "audio/webm":
+    default:
+      return "audio.webm";
+  }
+}
+
 const API_ERROR_MAX_BYTES = 16 * 1024;
 
 type ApiErrorRequestContext = {

package/src/core.ts

@@ -0,0 +1,19 @@
+export { OpenGeniClient as OpenGeniCoreClient } from "./client";
+export type {
+  FetchLike,
+  OpenGeniClientOptions,
+  OpenGeniRequestOptions,
+  SendMessageInput,
+  SteerMessageResult,
+  TranscribeAudioInput,
+  WorkspaceControlEventPage,
+} from "./client";
+export {
+  OpenGeniApiContractMismatchError,
+  OpenGeniApiError,
+  OpenGeniSessionListCursorError,
+  OpenGeniStreamError,
+  isRetryableStreamError,
+} from "./errors";
+export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
+export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";

package/src/index.ts

@@ -1,10 +1,11 @@
-export { OpenGeniClient } from "./client";
+export { OpenGeniClient } from "./artifact-client";
 export type {
   FetchLike,
   OpenGeniClientOptions,
   OpenGeniRequestOptions,
   SendMessageInput,
   SteerMessageResult,
+  TranscribeAudioInput,
   WorkspaceControlEventPage,
 } from "./client";
 export {
@@ -55,6 +56,19 @@ export type {
 } from "./stream";
 export { streamWorkspaceControlEvents } from "./workspace-control-stream";
 export type { WorkspaceControlStreamTransport } from "./workspace-control-stream";
+export type {
+  CreateWorkspaceArtifactRequest,
+  PublishWorkspaceArtifactVersionRequest,
+  RollbackWorkspaceArtifactRequest,
+  WorkspaceArtifact,
+  WorkspaceArtifactContentResponse,
+  WorkspaceArtifactDetailResponse,
+  WorkspaceArtifactEvent,
+  WorkspaceArtifactListOptions,
+  WorkspaceArtifactListResponse,
+  WorkspaceArtifactMutationResponse,
+  WorkspaceArtifactVersion,
+} from "./workspace-artifacts";
 export { normalizeWorkspaceInstructionPolicyRoleKey } from "./workspace-instruction-policies";
 export type {
   ActivateWorkspaceInstructionPolicyRequest,
@@ -78,10 +92,47 @@ export type {
   WorkspaceInstructionPolicyScope,
   WorkspaceInstructionPolicyTarget,
 } from "./workspace-instruction-policies";
+export type {
+  WorkspaceStateDocumentStatusCounts,
+  WorkspaceStateGapCode,
+  WorkspaceStateMemoryKindCounts,
+  WorkspaceStateMemoryStatusCounts,
+  WorkspaceStateResponse,
+  WorkspaceStateSourceKindCounts,
+} from "./workspace-state";
+export { normalizePreferenceRegistryStableKey } from "./preference-registry";
+export type {
+  ActivatePreferenceRegistryRevisionRequest,
+  ChangePreferenceRegistryScopeRequest,
+  CorrectPreferenceRegistryRequest,
+  CreatePreferenceRegistryProposalRequest,
+  DeactivatePreferenceRegistryRequest,
+  PreferenceRegistryConflictStrategy,
+  PreferenceRegistryDescriptor,
+  PreferenceRegistryDescriptorProvenance,
+  PreferenceRegistryDetailResponse,
+  PreferenceRegistryEvent,
+  PreferenceRegistryFullContent,
+  PreferenceRegistryListOptions,
+  PreferenceRegistryListResponse,
+  PreferenceRegistryMutationResponse,
+  PreferenceRegistryPrecedence,
+  PreferenceRegistryProvenanceSource,
+  PreferenceRegistryRecord,
+  PreferenceRegistryRevisionSummary,
+  PreferenceRegistryScope,
+  PreferenceRegistryScopeTarget,
+  PreferenceRegistrySnapshot,
+  PreferenceRegistryStatus,
+  PreferenceRegistryTrust,
+  RejectPreferenceRegistryProposalRequest,
+  SupersedePreferenceRegistryRequest,
+} from "./preference-registry";
 export {
   DEFAULT_WORKSPACE_TRANSCRIPTION_POLICY,
   authorizeTranscriptionAdapter,
   createTranscriptionSessionRequest,
+  resolveWorkspaceVoiceInputEnabled,
   resolveWorkspaceTranscriptionPolicy,
 } from "./transcription";
 export type {
@@ -132,6 +183,19 @@ export type {
   BillingMode,
   BillingSummary,
   BillingUsageResponse,
+  InsightsRange,
+  InsightsBillingPath,
+  InsightsModelUsageRow,
+  InsightsSeriesPoint,
+  InsightsDepthBucket,
+  InsightsModelFacet,
+  InsightsSpendDriver,
+  InsightsWarmGroupRow,
+  InsightsLiveWarmLease,
+  InsightsFloorSession,
+  InsightsScheduleRow,
+  WorkspaceInsightsSnapshot,
+  WorkspaceInsightsResponse,
   CapabilityCatalogItem,
   CapabilityCatalogResponse,
   CapabilityInstallation,
@@ -149,6 +213,7 @@ export type {
   CapabilitySource,
   CapabilityUnavailableReason,
   ClientConfig,
+  ClientVoiceInputConfig,
   ClientModel,
   ModelAvailabilityV1,
   ModelBillingAttributionV1,
@@ -245,6 +310,15 @@ export type {
   GitHubInstallationBinding,
   GitHubInstallationLifecycle,
   GitHubRepositoriesResponse,
+  GoogleDriveBrowseItem,
+  GoogleDriveBrowseResponse,
+  GoogleDriveConnectionMetadata,
+  GoogleDriveOAuthStartRequest,
+  GoogleDriveOAuthStartResponse,
+  GoogleDriveReadPolicy,
+  GoogleDriveSelectedSource,
+  GoogleDriveSyncCadence,
+  GoogleDriveTargetScope,
   GitHubRepository,
   GitHubRepositoryScope,
   GoalSpec,
@@ -272,6 +346,7 @@ export type {
   PackInstallationStatus,
   Permission,
   ProductAccessMode,
+  LatencyMode,
   ReasoningEffort,
   RetainedArtifactContent,
   RetainedArtifactContentOptions,
@@ -290,6 +365,7 @@ export type {
   RegisterCapabilityPackRequest,
   RepositoryResourceRef,
   ResourceRef,
+  SaveGoogleDriveSourceRequest,
   SandboxBackend,
   SandboxCapabilityName,
   SandboxOs,
@@ -455,6 +531,7 @@ export type {
   UpdateWorkspaceMemberRequest,
   UpdateWorkspaceRequest,
   UpdateWorkspaceSettingsRequest,
+  TranscribeAudioResponse,
   UploadFileInput,
   UsageEvent,
   UsageEventType,
@@ -486,6 +563,7 @@ export type {
   WorkspaceMemorySearchResult,
   WorkspaceMemorySearchResponse,
   WorkspaceSettings,
+  WorkspaceVoiceInputSettings,
   WorkspaceRegisteredPack,
   // Bring-your-own-compute: Machines dashboard + per-machine metrics (M10).
   MetricSample,