@opengeni/api-router 0.23.1 → 0.26.1

package/src/memory-slack-delivery.ts

@@ -0,0 +1,209 @@
+import {
+  claimMemorySlackPublication,
+  completeMemorySlackPublication,
+  currentMemorySlackConfigurationMatches,
+  deferMemorySlackPublication,
+  failMemorySlackPublication,
+  type ClaimedMemorySlackPublication,
+} from "@opengeni/db";
+import { sanitizeSlackPublicationText, type ApiRouteDeps } from "@opengeni/core";
+import {
+  createOpenGeniSlackBotInteractionClient,
+  SlackBotProviderError,
+} from "./integrations/slack-bot";
+
+const DELIVERY_LEASE_MS = 30_000;
+const MAX_DELIVERY_ATTEMPTS = 8;
+const MAX_DELIVERY_RETRY_MS = 5 * 60_000;
+const MAX_SLACK_MESSAGE_CHARS = 3_500;
+
+export async function drainMemorySlackPublicationsOnce(deps: ApiRouteDeps): Promise<boolean> {
+  const claimHolderId = crypto.randomUUID();
+  const publication = await claimMemorySlackPublication(deps.db, claimHolderId, DELIVERY_LEASE_MS);
+  if (!publication) return false;
+
+  try {
+    if (!(await currentMemorySlackConfigurationMatches(deps.db, publication))) {
+      await failMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode: "configuration_changed",
+        cancelled: true,
+      });
+      return true;
+    }
+    const client = await createOpenGeniSlackBotInteractionClient(deps, {
+      accountId: publication.accountId,
+      workspaceId: publication.workspaceId,
+      connectionId: publication.connectionId,
+      subjectId: publication.initiatorSubjectId,
+      sessionId: publication.sessionId,
+    });
+    const result = await client.postMessage({
+      operationId: publication.operationId,
+      channelId: publication.slackChannelId,
+      text: formatMemorySlackPublicationMessage(deps, publication),
+      requireActiveNonSharedChannel: true,
+    });
+    const completed = await completeMemorySlackPublication(deps.db, {
+      publication,
+      claimHolderId,
+      slackChannelId: result.channelId,
+      slackMessageTimestamp: result.timestamp,
+    });
+    if (!completed) throw new Error("Memory Slack publication lost its durable claim");
+  } catch (error) {
+    const errorCode = deliveryErrorCode(error);
+    if (memorySlackDestinationDrift(error)) {
+      await failMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode,
+        cancelled: true,
+      }).catch(() => undefined);
+    } else if (publication.attemptCount >= MAX_DELIVERY_ATTEMPTS || permanentDeliveryError(error)) {
+      await failMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode,
+      }).catch(() => undefined);
+    } else {
+      await deferMemorySlackPublication(deps.db, {
+        publication,
+        claimHolderId,
+        errorCode,
+        retryAt: new Date(Date.now() + deliveryRetryMs(error, publication.attemptCount)),
+      }).catch(() => undefined);
+    }
+  }
+  return true;
+}
+
+export function startMemorySlackPublicationPump(
+  deps: ApiRouteDeps,
+  options: { intervalMs?: number; maxPerTick?: number } = {},
+): () => Promise<void> {
+  let stopped = false;
+  let running: Promise<void> | undefined;
+  const intervalMs = Math.max(250, options.intervalMs ?? 1_000);
+  const maxPerTick = Math.max(1, Math.min(50, options.maxPerTick ?? 10));
+  const tick = () => {
+    if (stopped || running) return;
+    running = (async () => {
+      for (let index = 0; index < maxPerTick; index += 1) {
+        if (!(await drainMemorySlackPublicationsOnce(deps))) break;
+      }
+    })()
+      .catch((error) => {
+        deps.observability?.error("Memory Slack publication claim failed", {
+          errorClass: error instanceof Error ? error.name : "MemorySlackPublicationPumpError",
+          errorCode: deliveryErrorCode(error),
+          origin: "api",
+        });
+      })
+      .finally(() => {
+        running = undefined;
+      });
+  };
+  const timer = setInterval(tick, intervalMs);
+  queueMicrotask(tick);
+  return async () => {
+    stopped = true;
+    clearInterval(timer);
+    await running;
+  };
+}
+
+export function formatMemorySlackPublicationMessage(
+  deps: Pick<ApiRouteDeps, "settings">,
+  publication: ClaimedMemorySlackPublication,
+): string {
+  const projection = publication.projection;
+  const summary = boundedProjectionString(projection["summary"], 512) || "Important change";
+  const owner = boundedProjectionString(projection["ownerLabel"], 96);
+  const occurredAt = boundedProjectionString(projection["occurredAt"], 64);
+  const changeKind = boundedProjectionString(projection["changeKind"], 32);
+  const destination = boundedProjectionString(projection["destination"], 64);
+  const outcome = boundedProjectionString(projection["outcome"], 64);
+  const heading =
+    publication.sourceType === "workspace_memory"
+      ? `Workspace Memory ${changeKind || "change"}`
+      : `Governed learning ${outcome || "change"}`;
+  const details = [
+    `Importance: ${publication.importance}`,
+    ...(destination ? [`Surface: ${destination}`] : []),
+    ...(owner ? [`Owner: ${owner}`] : []),
+    ...(occurredAt ? [`Recorded: ${occurredAt}`] : []),
+  ];
+  const path =
+    publication.sourceType === "workspace_memory"
+      ? `/workspaces/${publication.workspaceId}/memory?memoryId=${encodeURIComponent(publication.sourceId)}`
+      : `/workspaces/${publication.workspaceId}/workspace-state`;
+  const base = deps.settings.webBaseUrl ?? deps.settings.publicBaseUrl;
+  const link = base ? new URL(path, base).toString() : null;
+  const text = `*${heading}*\n${summary}\n\n${details.join(" · ")}${link ? `\n${link}` : ""}`;
+  return text.length <= MAX_SLACK_MESSAGE_CHARS
+    ? text
+    : `${text.slice(0, MAX_SLACK_MESSAGE_CHARS - 20)}\n… message truncated`;
+}
+
+const PERMANENT_DELIVERY_CODES = new Set([
+  "account_inactive",
+  "channel_not_found",
+  "invalid_auth",
+  "is_archived",
+  "not_authed",
+  "not_in_channel",
+  "token_expired",
+  "token_revoked",
+]);
+
+const MEMORY_SLACK_DESTINATION_DRIFT_CODES = new Set([
+  "channel_not_found",
+  "is_archived",
+  "not_in_channel",
+  "slack_connect_unsupported",
+]);
+
+export function memorySlackDestinationDrift(error: unknown) {
+  return (
+    error instanceof SlackBotProviderError && MEMORY_SLACK_DESTINATION_DRIFT_CODES.has(error.code)
+  );
+}
+
+function permanentDeliveryError(error: unknown) {
+  if (!(error instanceof SlackBotProviderError)) return false;
+  if (PERMANENT_DELIVERY_CODES.has(error.code)) return true;
+  const status = /^http_(\d{3})$/.exec(error.code)?.[1];
+  return status
+    ? Number(status) >= 400 && Number(status) < 500 && status !== "408" && status !== "429"
+    : false;
+}
+
+function deliveryRetryMs(error: unknown, attemptCount: number) {
+  if (error instanceof SlackBotProviderError && error.retryAfterMs) {
+    return Math.min(Math.max(error.retryAfterMs, 1_000), MAX_DELIVERY_RETRY_MS);
+  }
+  return Math.min(1_000 * 2 ** Math.max(0, attemptCount - 1), MAX_DELIVERY_RETRY_MS);
+}
+
+function deliveryErrorCode(error: unknown) {
+  if (error instanceof SlackBotProviderError) return error.code.slice(0, 128);
+  const raw = error instanceof Error ? error.name : "memory_slack_delivery_error";
+  return (
+    raw
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]/g, "_")
+      .slice(0, 128) || "error"
+  );
+}
+
+function boundedProjectionString(value: unknown, maxChars: number) {
+  return typeof value === "string"
+    ? escapeSlackText(sanitizeSlackPublicationText(value).slice(0, maxChars))
+    : "";
+}
+
+function escapeSlackText(value: string) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}

package/src/routes/api-integrations.ts

@@ -0,0 +1,407 @@
+import {
+  CORE_PROVIDER_PRESETS,
+  createPinnedIntegrationTransport,
+  integrationFeaturesForPreset,
+  providerDomainForPreset,
+  type IntegrationCredentialResolver,
+} from "@opengeni/capabilities";
+import {
+  ApiIntegrationPreview,
+  ListApiIntegrationPresetsResponse,
+  ApiIntegrationUninstallPreview,
+  InstallApiIntegrationRequest,
+  InstalledApiIntegration,
+  ListApiIntegrationsResponse,
+  PreviewApiIntegrationRequest,
+  UninstallApiIntegrationRequest,
+  UninstallApiIntegrationResult,
+} from "@opengeni/contracts";
+import { requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  ApiIntegrationInstallationVersionConflictError,
+  buildConnectionTokenResolver,
+  getApiIntegrationUninstallPreview,
+  getConnectionMetadata,
+  installApiIntegration,
+  IntegrationFeatureBindingOwnershipConflictError,
+  IntegrationFeatureBindingVersionConflictError,
+  IntegrationFeatureBindingVersionRequiredError,
+  listInstalledApiIntegrations,
+  uninstallApiIntegration,
+  type ConnectionMetadataWithVerification,
+} from "@opengeni/db";
+import type { FetchLike } from "@opengeni/network";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+import {
+  resolveApiIntegrationPreview,
+  type ApiIntegrationConnectionDescriptor,
+} from "../integrations/api-integrations";
+
+export type ApiIntegrationRouteOverrides = Readonly<{ fetchImpl?: FetchLike }>;
+
+export function apiIntegrationRequiresConnection(authScheme: Record<string, unknown>): boolean {
+  const authKind = authScheme.kind;
+  return typeof authKind === "string" && authKind !== "none";
+}
+
+export function registerApiIntegrationRoutes(
+  app: Hono,
+  deps: ApiRouteDeps,
+  overrides: ApiIntegrationRouteOverrides = {},
+): void {
+  const transport = createPinnedIntegrationTransport({
+    network: deps.settings,
+    ...(overrides.fetchImpl ? { fetchImpl: overrides.fetchImpl } : {}),
+  });
+
+  app.get("/v1/workspaces/:workspaceId/integrations/presets", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    return c.json(
+      ListApiIntegrationPresetsResponse.parse({
+        presets: CORE_PROVIDER_PRESETS.map((preset) => ({
+          id: preset.id,
+          name: preset.name,
+          summary: preset.summary,
+          family: preset.family,
+          protocol: "openapi",
+          providerDomain: providerDomainForPreset(preset),
+          scopes: [...preset.oauth.scopes],
+          features: preset.features.map((feature) => ({
+            featureKey: feature.featureKey,
+            kind: feature.kind,
+            configSchema: { ...feature.configSchema },
+            capabilities: { ...feature.capabilities },
+          })),
+        })),
+      }),
+    );
+  });
+
+  app.get("/v1/workspaces/:workspaceId/integrations", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const integrations = await listInstalledApiIntegrations(deps.db, workspaceId, grant.subjectId);
+    return c.json(
+      ListApiIntegrationsResponse.parse({
+        integrations: integrations.map((integration) => {
+          return {
+            capabilityId: integration.capabilityId,
+            pluginKey: integration.pluginKey,
+            installationVersion: integration.installationVersion,
+            instanceId: integration.instanceId,
+            instanceKey: integration.instanceKey,
+            displayName: integration.displayName,
+            instanceVersion: integration.instanceVersion,
+            serverId: integration.serverId,
+            name: integration.name,
+            description: integration.description,
+            protocol: integration.protocol,
+            presetId: integration.presetId,
+            providerDomain: integration.providerDomain,
+            baseUrl: integration.baseUrl,
+            sourceUrl: integration.sourceUrl,
+            connected: integration.connectionRef !== null,
+            requiresConnection: apiIntegrationRequiresConnection(integration.authScheme),
+            connectionId: integration.connectionRef?.connectionId ?? null,
+            ownership:
+              integration.connectionRef?.subjectScope === "subject"
+                ? "personal"
+                : integration.connectionRef
+                  ? "workspace"
+                  : "none",
+            allowedTools: integration.allowedTools,
+            toolCount: integration.allowedTools.length,
+            approvalRequiredToolCount:
+              integration.requireApproval === true
+                ? integration.allowedTools.length
+                : integration.requireApproval.length,
+            revisionId: integration.revision.id,
+            contentSha256: integration.revision.contentSha256,
+          };
+        }),
+      }),
+    );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/integrations/preview", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const payload = PreviewApiIntegrationRequest.parse(await c.req.json());
+    const resolved = await resolveForRoute({
+      deps,
+      transport,
+      workspaceId,
+      subjectId: grant.subjectId,
+      payload,
+    });
+    return c.json(ApiIntegrationPreview.parse(resolved.preview));
+  });
+
+  app.post("/v1/workspaces/:workspaceId/integrations/install", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const payload = InstallApiIntegrationRequest.parse(await c.req.json());
+    const resolved = await resolveForRoute({
+      deps,
+      transport,
+      workspaceId,
+      subjectId: grant.subjectId,
+      payload,
+    });
+    if (
+      resolved.preview.revisionId !== payload.expectedRevisionId ||
+      resolved.preview.contentSha256 !== payload.expectedContentSha256
+    ) {
+      throw new HTTPException(409, {
+        message:
+          "The Integration source changed after preview. Review the new tools and permissions before installing.",
+      });
+    }
+    if (resolved.preview.auth.kind !== "none" && !payload.connectionId) {
+      throw new HTTPException(422, {
+        message: "Connect an account before installing this Integration.",
+      });
+    }
+    if (
+      payload.ownership &&
+      resolved.preview.connectionOwnership &&
+      payload.ownership !== resolved.preview.connectionOwnership
+    ) {
+      throw new HTTPException(422, {
+        message: "The selected Connection ownership does not match this install request.",
+      });
+    }
+    if (payload.ownership === "personal" && !resolved.preview.connectionOwnership) {
+      throw new HTTPException(422, {
+        message: "Choose a Personal Connection before installing for yourself.",
+      });
+    }
+    try {
+      return c.json(
+        InstalledApiIntegration.parse(
+          await installApiIntegration(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            subjectId: grant.subjectId,
+            capabilityId: resolved.preview.capabilityId,
+            pluginKey: resolved.preview.pluginKey,
+            serverId: resolved.preview.serverId,
+            name: resolved.preview.name,
+            description: resolved.preview.description,
+            category: "integrations",
+            tags: [resolved.preview.protocol, resolved.preview.provider ?? "custom"],
+            presetId: resolved.preview.presetId,
+            ...(resolved.provider ? { provider: resolved.provider } : {}),
+            providerDomain: resolved.preview.providerDomain,
+            protocol: resolved.preview.protocol,
+            baseUrl: resolved.preview.baseUrl,
+            sourceUrl: resolved.preview.sourceUrl,
+            authScheme: resolved.authScheme,
+            ...(payload.connectionId ? { connectionId: payload.connectionId } : {}),
+            ...(payload.instanceKey ? { instanceKey: payload.instanceKey } : {}),
+            ...(payload.displayName ? { displayName: payload.displayName } : {}),
+            ...(payload.expectedInstanceVersion !== undefined
+              ? { expectedInstanceVersion: payload.expectedInstanceVersion }
+              : {}),
+            requiredScopes: resolved.requiredScopes,
+            ownership:
+              resolved.preview.connectionOwnership === "personal" ? "subject" : "workspace",
+            ...(payload.allowedTools ? { allowedTools: payload.allowedTools } : {}),
+            featureDefinitions: integrationFeaturesForPreset(resolved.preview.presetId),
+            revision: resolved.revision,
+          }),
+        ),
+        payload.expectedInstanceVersion === undefined ? 201 : 200,
+      );
+    } catch (error) {
+      if (
+        error instanceof IntegrationFeatureBindingVersionConflictError ||
+        error instanceof IntegrationFeatureBindingVersionRequiredError ||
+        error instanceof IntegrationFeatureBindingOwnershipConflictError
+      ) {
+        throw new HTTPException(409, {
+          message:
+            "The Integration instance changed or is shared by another owner. Refresh its details before updating it.",
+        });
+      }
+      throw error;
+    }
+  });
+
+  app.get(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/uninstall-preview",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+      return c.json(
+        ApiIntegrationUninstallPreview.parse(
+          await getApiIntegrationUninstallPreview(
+            deps.db,
+            workspaceId,
+            grant.subjectId,
+            decodeURIComponent(c.req.param("capabilityId")),
+            decodeURIComponent(c.req.param("instanceKey")),
+          ),
+        ),
+      );
+    },
+  );
+
+  app.delete(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+      const capabilityId = decodeURIComponent(c.req.param("capabilityId"));
+      const instanceKey = decodeURIComponent(c.req.param("instanceKey"));
+      const payload = UninstallApiIntegrationRequest.parse(await c.req.json());
+      try {
+        return c.json(
+          UninstallApiIntegrationResult.parse(
+            await uninstallApiIntegration(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              subjectId: grant.subjectId,
+              capabilityId,
+              instanceKey,
+              expectedInstallationVersion: payload.expectedInstallationVersion,
+              expectedInstanceVersion: payload.expectedInstanceVersion,
+            }),
+          ),
+        );
+      } catch (error) {
+        if (
+          error instanceof ApiIntegrationInstallationVersionConflictError ||
+          error instanceof IntegrationFeatureBindingVersionConflictError
+        ) {
+          throw new HTTPException(409, {
+            message:
+              "The Integration instance changed after preview. Review uninstall impact again.",
+          });
+        }
+        throw error;
+      }
+    },
+  );
+}
+
+async function resolveForRoute(input: {
+  deps: ApiRouteDeps;
+  transport: ReturnType<typeof createPinnedIntegrationTransport>;
+  workspaceId: string;
+  subjectId: string;
+  payload: PreviewApiIntegrationRequest | InstallApiIntegrationRequest;
+}): ReturnType<typeof resolveApiIntegrationPreview> {
+  try {
+    const connection = input.payload.connectionId
+      ? await requireVisibleConnection(
+          input.deps,
+          input.workspaceId,
+          input.subjectId,
+          input.payload.connectionId,
+        )
+      : null;
+    return await resolveApiIntegrationPreview({
+      source: input.payload.source,
+      connection: connectionDescriptor(connection),
+      transport: input.transport,
+      authority: {
+        accountId: connection?.accountId ?? "preview",
+        workspaceId: input.workspaceId,
+        initiatingSubjectId: input.subjectId,
+        ...(connection ? { connectionRef: connection.id } : {}),
+      },
+      ...(connection
+        ? {
+            credentialResolver: previewCredentialResolver(
+              input.deps,
+              input.workspaceId,
+              input.subjectId,
+              connection,
+            ),
+          }
+        : {}),
+    });
+  } catch (error) {
+    if (error instanceof HTTPException) throw error;
+    throw new HTTPException(422, {
+      message:
+        error instanceof Error
+          ? error.message
+          : "The Integration source could not be detected safely",
+    });
+  }
+}
+
+async function requireVisibleConnection(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  subjectId: string,
+  connectionId: string,
+): Promise<ConnectionMetadataWithVerification> {
+  const connection = await getConnectionMetadata(deps.db, workspaceId, connectionId, subjectId);
+  if (!connection) throw new HTTPException(404, { message: "connection not found" });
+  if (connection.status !== "active") {
+    throw new HTTPException(422, { message: "connection is not active" });
+  }
+  return connection;
+}
+
+function connectionDescriptor(
+  connection: ConnectionMetadataWithVerification | null,
+): ApiIntegrationConnectionDescriptor | null {
+  return connection
+    ? {
+        id: connection.id,
+        kind: connection.kind,
+        providerDomain: connection.providerDomain,
+        scopes: [...connection.grantedScopes],
+        ownership: connection.subjectId ? "personal" : "workspace",
+      }
+    : null;
+}
+
+function previewCredentialResolver(
+  deps: ApiRouteDeps,
+  workspaceId: string,
+  subjectId: string,
+  connection: ConnectionMetadataWithVerification,
+): IntegrationCredentialResolver {
+  const resolve = buildConnectionTokenResolver(deps.db, deps.settings);
+  return {
+    resolve: async (request) => {
+      const result = await resolve({
+        workspaceId,
+        ...(connection.subjectId ? { subjectId } : {}),
+        serverId: `preview_${connection.id}`,
+        toolName: request.operationKey,
+        connectionRef: {
+          connectionId: connection.id,
+          providerDomain: connection.providerDomain,
+          kind: connection.kind,
+          ...(connection.grantedScopes.length > 0 ? { scopes: [...connection.grantedScopes] } : {}),
+          subjectScope: connection.subjectId ? "subject" : "workspace",
+        },
+        destinationUrl: request.destinationUrl,
+        credentialTarget: "http_api",
+        forceRefresh: request.forceRefresh === true,
+      });
+      if (result.status === "auth_needed") return null;
+      const destination = new URL(request.destinationUrl);
+      return {
+        audience: { origin: destination.origin, pathPrefix: "/" },
+        placements:
+          result.placements ??
+          Object.entries(result.headers).map(([name, value]) => ({
+            carrier: "header" as const,
+            name,
+            value,
+          })),
+        ...(result.expiresAt ? { expiresAt: result.expiresAt.toISOString() } : {}),
+      };
+    },
+  };
+}