@opengeni/sdk 3.3.2-canary.1 → 3.4.0

package/src/workspace-integrations.ts

@@ -0,0 +1,402 @@
+import {
+  OPENGENI_DELIVERY_ID_HEADER,
+  OPENGENI_EVENT_ID_HEADER,
+  OPENGENI_SIGNATURE_HEADER,
+  OPENGENI_WEBHOOK_TEST_EVENT_TYPE,
+  verifyOpenGeniSignature,
+} from "@opengeni/contracts/workspace-integration-wire";
+import type { CredentialProviderRequest, WorkspaceWebhookEvent } from "@opengeni/contracts";
+import type { OpenGeniClient } from "./client";
+import type {
+  CreateOrganizationWebhookRequest,
+  CreateOrganizationWebhookResponse,
+  GetOrganizationCredentialProviderResponse,
+  ListOrganizationWebhookDeliveriesResponse,
+  ListOrganizationWebhooksResponse,
+  OrganizationWebhook,
+  OrganizationWebhookDelivery,
+  PutOrganizationCredentialProviderRequest,
+  PutOrganizationCredentialProviderResponse,
+  RotateWorkspaceCredentialProviderSecretResponse,
+  RotateOrganizationCredentialProviderSecretResponse,
+  RotateWorkspaceWebhookSecretResponse,
+  RotateOrganizationWebhookSecretResponse,
+  TestWorkspaceCredentialProviderResponse,
+  TestWorkspaceWebhookResponse,
+  UpdateOrganizationWebhookRequest,
+  WorkspaceInheritedIntegrationsResponse,
+  WorkspaceWebhook,
+} from "@opengeni/contracts";
+
+export type {
+  CreateOrganizationWebhookRequest,
+  CreateOrganizationWebhookResponse,
+  CreateWorkspaceWebhookRequest,
+  CreateWorkspaceWebhookResponse,
+  CredentialProviderRequest,
+  CredentialProviderInitiatorContext,
+  CredentialProviderResponse,
+  CredentialProviderMcpHeaders,
+  CredentialProviderMcpMaterial,
+  GetOrganizationCredentialProviderResponse,
+  GetWorkspaceCredentialProviderResponse,
+  InitiatingHuman,
+  IntegrationEndpointTestResult,
+  IntegrationWorkspaceFilter,
+  ListOrganizationWebhookDeliveriesResponse,
+  ListOrganizationWebhooksResponse,
+  ListWorkspaceWebhookDeliveriesResponse,
+  ListWorkspaceWebhooksResponse,
+  PutWorkspaceCredentialProviderRequest,
+  PutWorkspaceCredentialProviderResponse,
+  PutOrganizationCredentialProviderRequest,
+  PutOrganizationCredentialProviderResponse,
+  RotateWorkspaceCredentialProviderSecretResponse,
+  RotateOrganizationCredentialProviderSecretResponse,
+  RotateWorkspaceWebhookSecretResponse,
+  RotateOrganizationWebhookSecretResponse,
+  TestWorkspaceCredentialProviderResponse,
+  TestWorkspaceWebhookResponse,
+  OrganizationCredentialProvider,
+  OrganizationWebhook,
+  OrganizationWebhookDelivery,
+  UpdateOrganizationWebhookRequest,
+  UpdateWorkspaceWebhookRequest,
+  WorkspaceCredentialProvider,
+  WorkspaceInheritedIntegrationsResponse,
+  WorkspaceTestWebhookEvent,
+  WorkspaceWebhook,
+  WorkspaceWebhookDelivery,
+  WorkspaceWebhookEvent,
+  WorkspaceWebhookEventType,
+  SessionWorkspaceWebhookEvent,
+  WorkspaceUsageWebhookEvent,
+} from "@opengeni/contracts";
+export {
+  OPENGENI_DELIVERY_ID_HEADER,
+  OPENGENI_EVENT_ID_HEADER,
+  OPENGENI_SIGNATURE_HEADER,
+  OPENGENI_TEST_REQUEST_NIL_ID,
+  OPENGENI_WEBHOOK_TEST_EVENT_TYPE,
+  WORKSPACE_WEBHOOK_EVENT_TYPES,
+  signOpenGeniPayload,
+  verifyOpenGeniSignature,
+} from "@opengeni/contracts/workspace-integration-wire";
+
+export type WorkspaceSandboxImages = { images: string[]; selected: string | null };
+
+export class OpenGeniSignatureError extends Error {
+  constructor() {
+    super("Opengeni signature verification failed");
+    this.name = "OpenGeniSignatureError";
+  }
+}
+
+type SignedRequest = {
+  /** The exact raw request body. Parse it only after verification. */
+  body: string;
+  headers: Headers | Record<string, string | string[] | undefined>;
+  secret: string;
+  toleranceSeconds?: number;
+};
+
+function header(headers: SignedRequest["headers"], name: string): string | null {
+  if (headers instanceof Headers) return headers.get(name);
+  const wanted = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === wanted) {
+      return Array.isArray(value) ? (value[0] ?? null) : (value ?? null);
+    }
+  }
+  return null;
+}
+
+async function verifiedObject(input: SignedRequest): Promise<Record<string, unknown>> {
+  const valid = await verifyOpenGeniSignature({
+    secret: input.secret,
+    body: input.body,
+    signature: header(input.headers, OPENGENI_SIGNATURE_HEADER),
+    ...(input.toleranceSeconds !== undefined ? { toleranceSeconds: input.toleranceSeconds } : {}),
+  });
+  if (!valid) throw new OpenGeniSignatureError();
+  const parsed: unknown = JSON.parse(input.body);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new OpenGeniSignatureError();
+  }
+  return parsed as Record<string, unknown>;
+}
+
+/**
+ * Verify and parse one webhook delivery. Delivery is at least once: dedupe on
+ * `event.id` (also sent as the `OpenGeni-Event-Id` header). A `webhook.test`
+ * event (from "Send test event") names no session: acknowledge it with 2xx.
+ */
+export async function verifyWebhookEvent(input: SignedRequest): Promise<{
+  event: WorkspaceWebhookEvent;
+  deliveryId: string | null;
+}> {
+  const event = await verifiedObject(input);
+  const usageEvent = typeof event.type === "string" && event.type.startsWith("usage.");
+  const lane = event.lane === undefined ? "workspace" : event.lane;
+  if (
+    typeof event.id !== "string" ||
+    typeof event.type !== "string" ||
+    typeof event.workspaceId !== "string" ||
+    (lane !== "workspace" && lane !== "organization") ||
+    (usageEvent && lane !== "workspace") ||
+    !(
+      typeof event.sessionId === "string" ||
+      ((event.sessionId === null || event.sessionId === undefined) &&
+        [
+          "usage.threshold_reached",
+          "usage.exhausted",
+          "usage.period_reset",
+          OPENGENI_WEBHOOK_TEST_EVENT_TYPE,
+        ].includes(event.type))
+    )
+  ) {
+    throw new OpenGeniSignatureError();
+  }
+  return {
+    event: { ...event, lane } as WorkspaceWebhookEvent,
+    deliveryId: header(input.headers, OPENGENI_DELIVERY_ID_HEADER),
+  };
+}
+
+/**
+ * Verify the exact bytes and parse a provider request, including its frozen
+ * initiatorContext when sent by an upgraded worker. Provenance grants no access.
+ */
+export async function verifyCredentialProviderRequest(
+  input: SignedRequest,
+): Promise<CredentialProviderRequest> {
+  const parsed = await verifiedObject(input);
+  if (parsed.type !== "credentials.request" || typeof parsed.workspaceId !== "string") {
+    throw new OpenGeniSignatureError();
+  }
+  return parsed as CredentialProviderRequest;
+}
+
+/** Identity header names, for receivers that log or dedupe. */
+export const OPENGENI_WEBHOOK_HEADERS = {
+  signature: OPENGENI_SIGNATURE_HEADER,
+  eventId: OPENGENI_EVENT_ID_HEADER,
+  deliveryId: OPENGENI_DELIVERY_ID_HEADER,
+} as const;
+
+/** Server-side integration administration is opt-in, outside the eager browser client. */
+export async function getOrganizationCredentialProvider(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+): Promise<GetOrganizationCredentialProviderResponse> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/credential-provider`,
+  );
+}
+
+/** Replace configuration; explicit filter required. Store the first returned signing secret. */
+export async function putOrganizationCredentialProvider(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  request: PutOrganizationCredentialProviderRequest,
+): Promise<PutOrganizationCredentialProviderResponse> {
+  return client.requestJson(
+    "PUT",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/credential-provider`,
+    request,
+  );
+}
+
+export async function deleteOrganizationCredentialProvider(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+): Promise<void> {
+  await client.requestJson<void>(
+    "DELETE",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/credential-provider`,
+    undefined,
+    {},
+    { responseType: "void" },
+  );
+}
+
+export async function listOrganizationWebhooks(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+): Promise<ListOrganizationWebhooksResponse> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks`,
+  );
+}
+
+/** Create a webhook and return its signing secret once. */
+export async function createOrganizationWebhook(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  request: CreateOrganizationWebhookRequest,
+): Promise<CreateOrganizationWebhookResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks`,
+    request,
+  );
+}
+
+export async function getOrganizationWebhook(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  webhookId: string,
+): Promise<OrganizationWebhook> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks/${encodeURIComponent(webhookId)}`,
+  );
+}
+
+export async function updateOrganizationWebhook(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  webhookId: string,
+  request: UpdateOrganizationWebhookRequest,
+): Promise<OrganizationWebhook> {
+  return client.requestJson(
+    "PATCH",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks/${encodeURIComponent(webhookId)}`,
+    request,
+  );
+}
+
+export async function deleteOrganizationWebhook(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  webhookId: string,
+): Promise<void> {
+  await client.requestJson<void>(
+    "DELETE",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks/${encodeURIComponent(webhookId)}`,
+    undefined,
+    {},
+    { responseType: "void" },
+  );
+}
+
+export async function listOrganizationWebhookDeliveries(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  webhookId: string,
+  options: { limit?: number } = {},
+): Promise<ListOrganizationWebhookDeliveriesResponse> {
+  return client.requestJson(
+    "GET",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks/${encodeURIComponent(webhookId)}/deliveries`,
+    undefined,
+    options.limit !== undefined ? { limit: String(options.limit) } : {},
+  );
+}
+
+/** Requeue a settled delivery with a fresh attempt budget. */
+export async function redeliverOrganizationWebhookDelivery(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  webhookId: string,
+  deliveryId: string,
+): Promise<OrganizationWebhookDelivery> {
+  return client.requestJson(
+    "POST",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks/${encodeURIComponent(webhookId)}/deliveries/${encodeURIComponent(deliveryId)}/redeliver`,
+  );
+}
+
+export async function getWorkspaceWebhook(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+  webhookId: string,
+): Promise<WorkspaceWebhook> {
+  return client.requestJson("GET", `/v1/workspaces/${workspaceId}/webhooks/${webhookId}`);
+}
+
+/** Rotate immediately. Store the new secret; the old signing secret stops working. */
+export async function rotateWorkspaceCredentialProviderSecret(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+): Promise<RotateWorkspaceCredentialProviderSecretResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/credential-provider/rotate-secret`,
+  );
+}
+
+export async function rotateOrganizationCredentialProviderSecret(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+): Promise<RotateOrganizationCredentialProviderSecretResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/credential-provider/rotate-secret`,
+  );
+}
+
+export async function rotateOrganizationWebhookSecret(
+  client: Pick<OpenGeniClient, "requestJson">,
+  organizationId: string,
+  webhookId: string,
+): Promise<RotateOrganizationWebhookSecretResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/organizations/${encodeURIComponent(organizationId)}/webhooks/${encodeURIComponent(webhookId)}/rotate-secret`,
+  );
+}
+
+export async function rotateWorkspaceWebhookSecret(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+  webhookId: string,
+): Promise<RotateWorkspaceWebhookSecretResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks/${encodeURIComponent(webhookId)}/rotate-secret`,
+  );
+}
+
+/**
+ * Send one signed `webhook.test` event to a workspace webhook now and return
+ * what the endpoint answered. Nothing is queued or retried.
+ */
+export async function testWorkspaceWebhook(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+  webhookId: string,
+): Promise<TestWorkspaceWebhookResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/webhooks/${encodeURIComponent(webhookId)}/test`,
+  );
+}
+
+/**
+ * Send one signed `purpose: "test"` request to the credential provider this
+ * workspace's runs use (its own, else the organization's). Only the names of
+ * returned credentials come back, never their values.
+ */
+export async function testWorkspaceCredentialProvider(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+): Promise<TestWorkspaceCredentialProviderResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/credential-provider/test`,
+  );
+}
+
+/** Organization registrations that reach this workspace. Workspace administrators only. */
+export async function getWorkspaceInheritedIntegrations(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+): Promise<WorkspaceInheritedIntegrationsResponse> {
+  return client.requestJson(
+    "GET",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/inherited-integrations`,
+  );
+}

package/src/workspace-state.ts

@@ -4,57 +4,6 @@ import type {
   WorkspaceInstructionPolicyScope,
 } from "./workspace-instruction-policies";
 
-export type WorkspaceStateDocumentStatusCounts = {
-  queued: number;
-  indexing: number;
-  ready: number;
-  failed: number;
-};
-
-export type WorkspaceStateSourceKindCounts = {
-  manual_upload: number;
-  meeting_transcript: number;
-  repository: number;
-  email: number;
-  chat: number;
-  document: number;
-  web: number;
-  other: number;
-};
-
-export type WorkspaceStateDocumentAuthorityKindCounts = {
-  organization: number;
-  workspace: number;
-  personal: number;
-};
-
-export type WorkspaceStateMemoryStatusCounts = {
-  proposed: number;
-  approved: number;
-  rejected: number;
-  active: number;
-  superseded: number;
-  archived: number;
-};
-
-export type WorkspaceStateMemoryKindCounts = {
-  semantic: number;
-  episodic: number;
-  procedural: number;
-  decision: number;
-  preference: number;
-};
-
-export type WorkspaceStateGapCode =
-  | "no_document_bases"
-  | "no_visible_documents"
-  | "failed_documents"
-  | "processing_documents"
-  | "missing_topic_coverage"
-  | "no_memory_records"
-  | "pending_memory_review"
-  | "partial_inventory";
-
 export type WorkspaceStateGovernanceDriftStatus =
   | "identical"
   | "changed"
@@ -188,39 +137,16 @@ export type WorkspaceStateResponse = {
       }
     | {
         availability: "available";
+        authority: "knowledge_entries";
         coverage: "complete" | "partial";
-        baseCount: number;
-        bases: Array<{
+        sampleLimit: 50;
+        entries: Array<{
           id: string;
-          name: string;
-          visibleDocumentCount: number;
-          statusCounts: WorkspaceStateDocumentStatusCounts;
-          latestUpdatedAt: string | null;
-        }>;
-        basesTruncated: boolean;
-        inspectedVisibleDocumentCount: number;
-        documentStatusCounts: WorkspaceStateDocumentStatusCounts;
-        sourceKindCounts: WorkspaceStateSourceKindCounts;
-        authorityKindCounts: WorkspaceStateDocumentAuthorityKindCounts;
-        topics: Array<{ name: string; documentCount: number }>;
-        topicsTruncated: boolean;
-        latestDocumentUpdatedAt: string | null;
-        memorySample: {
-          recordCount: number;
-          sampleLimit: 100;
-          limitReached: boolean;
-          statusCounts: WorkspaceStateMemoryStatusCounts;
-          kindCounts: WorkspaceStateMemoryKindCounts;
-          preferenceAuthority: {
-            kindCountSource: "knowledge_memories_legacy_observations";
-            activeAuthority: "structured_preference_registry";
-          };
-          latestUpdatedAt: string | null;
-        };
-        gaps: Array<{
-          code: WorkspaceStateGapCode;
-          severity: "info" | "warning";
-          relatedCount: number | null;
+          revisionId: string;
+          title: string;
+          kind: "source" | "fact" | "decision" | "requirement" | "incident" | "note" | "group";
+          scope: "organization" | "workspace" | "personal";
+          updatedAt: string;
         }>;
       };
 };