@opengeni/api-router 0.23.1 → 0.30.0

package/src/routes/files.ts

@@ -8,7 +8,10 @@ import {
   RETAINED_OUTPUT_MAX_PAGE_BYTES,
   RetainedArtifactMetadataSchema,
   retainedArtifactReferenceFromFile,
+  retainedGeneratedImageReferenceFromFile,
+  retainedGeneratedVideoReferenceFromFile,
   retainedScreenshotReferenceFromFile,
+  VideoArtifactPlaybackSource,
   resolveRetainedOutputRange,
   type RetainedArtifactMetadata,
   type RetainedOutputUnavailableReason,
@@ -19,10 +22,14 @@ import {
   completeFileUpload,
   createFileUpload,
   getFileUpload,
+  getGeneratedImageArtifact,
+  getGeneratedVideoArtifact,
   getRetainedFileArtifact,
   getRetainedScreenshotArtifact,
   requireFile,
   type RetainedFileArtifact,
+  type GeneratedImageArtifact,
+  type GeneratedVideoArtifact,
   type RetainedScreenshotArtifact,
 } from "@opengeni/db";
 import type { Context, Hono } from "hono";
@@ -270,18 +277,18 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "files:read");
     const artifactId = retainedArtifactId(c.req.param("artifactId"));
-    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    const artifact = await getWorkspaceArtifact(db, workspaceId, artifactId);
     if (!artifact) {
       return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
     }
-    return c.json(retainedArtifactMetadata(artifact));
+    return c.json(artifact.metadata);
   });
 
   app.get("/v1/workspaces/:workspaceId/artifacts/:artifactId/content", async (c) => {
     const workspaceId = c.req.param("workspaceId");
     await requireAccessGrant(c, deps, workspaceId, "files:read");
     const artifactId = retainedArtifactId(c.req.param("artifactId"));
-    const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+    const artifact = await getWorkspaceArtifact(db, workspaceId, artifactId);
     if (!artifact) {
       return c.json(retainedArtifactUnavailable(artifactId, "deleted"), 404);
     }
@@ -291,7 +298,40 @@ export function registerFileRoutes(app: Hono, deps: ApiRouteDeps): void {
       objectStorage,
       artifactId,
       artifact.file,
-      retainedArtifactMetadata(artifact),
+      artifact.metadata,
+    );
+  });
+
+  app.post("/v1/workspaces/:workspaceId/artifacts/:artifactId/playback-source", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    await requireAccessGrant(c, deps, workspaceId, "files:read");
+    if (!objectStorage) {
+      throw new HTTPException(503, { message: "object storage is not configured" });
+    }
+    const artifactId = retainedArtifactId(c.req.param("artifactId"));
+    const retained = await getGeneratedVideoArtifact(db, workspaceId, artifactId);
+    if (!retained || retained.artifact.deletedAt) {
+      throw new HTTPException(404, { message: "generated video not found" });
+    }
+    if (retained.file.status !== "ready") {
+      throw new HTTPException(409, { message: `generated video is ${retained.file.status}` });
+    }
+    const file = generatedVideoFileAsset(retained.file);
+    if (!(await objectStorage.fileExists(file))) {
+      throw new HTTPException(410, { message: "generated video bytes are unavailable" });
+    }
+    const signed = await objectStorage.createGetUrl({ key: file.objectKey });
+    return c.json(
+      VideoArtifactPlaybackSource.parse({
+        schemaVersion: 1,
+        artifactId,
+        url: signed.url,
+        expiresAt: signed.expiresAt.toISOString(),
+        contentType: "video/mp4",
+        sizeBytes: file.sizeBytes,
+        sha256: file.sha256,
+        acceptRanges: "bytes",
+      }),
     );
   });
 
@@ -495,6 +535,68 @@ function retainedArtifactMetadata(artifact: RetainedFileArtifact): RetainedArtif
   return retainedArtifactUnavailable(file.id, "unsupported");
 }
 
+async function getWorkspaceArtifact(
+  db: ApiRouteDeps["db"],
+  workspaceId: string,
+  artifactId: string,
+): Promise<{ file: RetainedFileArtifact["file"]; metadata: RetainedArtifactMetadata } | null> {
+  const generated = await getGeneratedImageArtifact(db, workspaceId, artifactId);
+  if (generated) {
+    return { file: generated.file, metadata: retainedGeneratedImageMetadata(generated) };
+  }
+  const generatedVideo = await getGeneratedVideoArtifact(db, workspaceId, artifactId);
+  if (generatedVideo && !generatedVideo.artifact.deletedAt) {
+    const file = generatedVideoFileAsset(generatedVideo.file);
+    return {
+      file,
+      metadata: retainedGeneratedVideoMetadata({
+        artifact: generatedVideo.artifact,
+        file,
+      }),
+    };
+  }
+  const artifact = await getRetainedFileArtifact(db, workspaceId, artifactId);
+  return artifact ? { file: artifact.file, metadata: retainedArtifactMetadata(artifact) } : null;
+}
+
+function generatedVideoFileAsset(
+  file: NonNullable<Awaited<ReturnType<typeof getGeneratedVideoArtifact>>>["file"],
+): RetainedFileArtifact["file"] {
+  return FileAsset.parse({
+    ...file,
+    createdAt: file.createdAt.toISOString(),
+    updatedAt: file.updatedAt.toISOString(),
+  });
+}
+
+function retainedGeneratedVideoMetadata(artifact: {
+  artifact: GeneratedVideoArtifact;
+  file: RetainedFileArtifact["file"];
+}): RetainedArtifactMetadata {
+  const reference = retainedGeneratedVideoReferenceFromFile({
+    ...artifact.file,
+    id: artifact.artifact.id,
+    width: artifact.artifact.width,
+    height: artifact.artifact.height,
+    updatedAt: artifact.artifact.readyAt.toISOString(),
+  });
+  return reference ?? retainedArtifactUnavailable(artifact.artifact.id, "failed");
+}
+
+function retainedGeneratedImageMetadata(
+  artifact: GeneratedImageArtifact,
+): RetainedArtifactMetadata {
+  if (artifact.status === "ready") {
+    const reference = retainedGeneratedImageReferenceFromFile({
+      ...artifact.file,
+      width: artifact.width,
+      height: artifact.height,
+    });
+    if (reference) return reference;
+  }
+  return retainedArtifactUnavailable(artifact.artifactId, "pending");
+}
+
 function retainedScreenshotMetadata(
   artifact: RetainedScreenshotArtifact,
 ): RetainedArtifactMetadata {

package/src/routes/github.ts

@@ -38,6 +38,7 @@ import {
   githubBrowserBaseUrl,
   githubBrowserGrantClaims,
   githubBrowserGrantFromState,
+  githubSessionReturnPath,
 } from "../github-browser-flow";
 import {
   githubBindingStatus,
@@ -64,12 +65,14 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     const status = githubBindingStatus(missing.length === 0, installations);
     const setupMode = settings.productAccessMode === "managed" ? "platform" : "operator";
     const canManage = hasPermission(grant.permissions, "github:manage");
+    const returnPath = githubSessionReturnPath(c.req.query("returnPath"), grant.workspaceId);
     const connectState =
       missing.length === 0 && slug && canManage
         ? createSignedState(githubStateSecret, {
             accountId: grant.accountId,
             workspaceId: grant.workspaceId,
             intent: "installation_authority",
+            ...(returnPath ? { returnPath } : {}),
             ...githubBrowserGrantClaims(settings, grant),
           })
         : null;
@@ -517,7 +520,12 @@ export function registerGitHubRoutes(app: Hono, deps: ApiRouteDeps): void {
     return c.html(
       githubSetupSuccessHtml(
         proof.installation.accountLogin ?? `installation ${installationId}`,
-        openGeniReturnUrl(settings, c, grant.workspaceId),
+        openGeniReturnUrl(
+          settings,
+          c,
+          grant.workspaceId,
+          typeof statePayload.returnPath === "string" ? statePayload.returnPath : null,
+        ),
       ),
     );
   });
@@ -879,8 +887,16 @@ function openGeniReturnUrl(
   settings: ApiRouteDeps["settings"],
   c: Context,
   workspaceId: string,
+  returnPath: string | null = null,
 ): string {
-  const url = new URL(openGeniBaseUrl(settings, c) || new URL(c.req.url).origin);
+  const baseUrl = openGeniBaseUrl(settings, c) || new URL(c.req.url).origin;
+  const safeReturnPath = githubSessionReturnPath(returnPath, workspaceId);
+  const url = safeReturnPath ? new URL(safeReturnPath, `${baseUrl}/`) : new URL(baseUrl);
+  if (safeReturnPath) {
+    url.searchParams.delete("capability_auth");
+    url.searchParams.set("github", "connected");
+    return url.toString();
+  }
   url.searchParams.set("workspaceId", workspaceId);
   return url.toString();
 }

package/src/routes/install.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
@@ -27,7 +28,12 @@ import type { ApiRouteDeps } from "@opengeni/core";
 // The committed install artifacts, resolved relative to this module so the API
 // (run from source under /app via bun) locates the sibling agent/install/ dir at
 // runtime. apps/api/src/routes -> ../../../../agent/install.
-const INSTALL_DIR = new URL("../../../../agent/install/", import.meta.url);
+const INSTALL_DIR =
+  [
+    new URL("./assets/agent-install/", import.meta.url),
+    new URL("../../../../agent/install/", import.meta.url),
+  ].find((candidate) => existsSync(candidate)) ??
+  new URL("../../../../agent/install/", import.meta.url);
 
 // The baked release-binary dir (a sibling of the committed scripts). The build's
 // signing step writes the per-SHA Linux musl binaries + their `.sha256`/`.minisig`

package/src/routes/integration-facets.ts

@@ -0,0 +1,258 @@
+import {
+  IntegrationFacetMutationResult,
+  IntegrationFacetRemovalResult,
+  IntegrationInstanceFacetsResponse,
+  MutateIntegrationFacetRequest,
+  UpsertIntegrationFacetRequest,
+} from "@opengeni/contracts";
+import {
+  hasPermission,
+  requireAccessGrant,
+  requireAccessGrantAuthorization,
+  type ApiRouteDeps,
+} from "@opengeni/core";
+import {
+  configureIntegrationFacet,
+  IntegrationFacetBindingOwnershipConflictError,
+  IntegrationFacetBindingVersionConflictError,
+  IntegrationFacetBindingVersionRequiredError,
+  IntegrationFacetConfigError,
+  IntegrationFacetConnectionError,
+  IntegrationFacetNotFoundError,
+  IntegrationFacetOperationIdempotencyError,
+  listIntegrationInstanceFacets,
+  removeIntegrationFacet,
+  setIntegrationFacetLifecycle,
+} from "@opengeni/db";
+import type { Hono } from "hono";
+import { HTTPException } from "hono/http-exception";
+
+import {
+  browseGoogleDriveFacetSource,
+  saveGoogleDriveFacetSource,
+} from "../integrations/google-drive";
+
+export function registerIntegrationFacetRoutes(app: Hono, deps: ApiRouteDeps): void {
+  app.get(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey/browse",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "connections:read");
+      try {
+        return c.json(
+          await browseGoogleDriveFacetSource(deps, {
+            workspaceId,
+            subjectId: grant.subjectId,
+            capabilityId: decoded(c.req.param("capabilityId")),
+            instanceKey: decoded(c.req.param("instanceKey")),
+            facetKey: decoded(c.req.param("facetKey")),
+            parentId: c.req.query("parentId") ?? "root",
+            ...(c.req.query("pageToken") ? { pageToken: c.req.query("pageToken") } : {}),
+          }),
+        );
+      } catch (error) {
+        throw facetHttpError(error);
+      }
+    },
+  );
+
+  app.put(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey/source",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const authorization = await requireAccessGrantAuthorization(
+        c,
+        deps,
+        workspaceId,
+        "workspace:admin",
+      );
+      const { grant } = authorization;
+      try {
+        return c.json(
+          IntegrationFacetMutationResult.parse(
+            await saveGoogleDriveFacetSource(deps, {
+              accountId: grant.accountId,
+              workspaceId,
+              subjectId: grant.subjectId,
+              capabilityId: decoded(c.req.param("capabilityId")),
+              instanceKey: decoded(c.req.param("instanceKey")),
+              facetKey: decoded(c.req.param("facetKey")),
+              payload: await c.req.json(),
+              canManageOrganizationDestination:
+                authorization.accountGrant?.permissions.includes("account:admin") === true,
+              canManageWorkspaceDestination: hasPermission(grant.permissions, "workspace:admin"),
+              canManagePersonalDestination:
+                authorization.contextIntegrity &&
+                authorization.authenticatedSubjectId === grant.subjectId,
+            }),
+          ),
+        );
+      } catch (error) {
+        throw facetHttpError(error);
+      }
+    },
+  );
+
+  app.get(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+      try {
+        return c.json(
+          IntegrationInstanceFacetsResponse.parse(
+            await listIntegrationInstanceFacets(
+              deps.db,
+              workspaceId,
+              grant.subjectId,
+              decoded(c.req.param("capabilityId")),
+              decoded(c.req.param("instanceKey")),
+            ),
+          ),
+        );
+      } catch (error) {
+        throw facetHttpError(error);
+      }
+    },
+  );
+
+  app.put(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+      const payload = UpsertIntegrationFacetRequest.parse(await c.req.json());
+      const capabilityId = decoded(c.req.param("capabilityId"));
+      const instanceKey = decoded(c.req.param("instanceKey"));
+      const facetKey = decoded(c.req.param("facetKey"));
+      try {
+        const instance = await listIntegrationInstanceFacets(
+          deps.db,
+          workspaceId,
+          grant.subjectId,
+          capabilityId,
+          instanceKey,
+        );
+        const definition = instance.facets.find(
+          (facet) => facet.definition.facetKey === facetKey,
+        )?.definition;
+        if (
+          definition?.kind === "knowledge_source" &&
+          definition.capabilities.provider === "google-drive"
+        ) {
+          throw new HTTPException(422, {
+            message:
+              "Google Drive source configuration requires the provider-specific source route",
+          });
+        }
+        return c.json(
+          IntegrationFacetMutationResult.parse(
+            await configureIntegrationFacet(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              subjectId: grant.subjectId,
+              capabilityId,
+              instanceKey,
+              facetKey,
+              displayName: payload.displayName,
+              config: payload.config,
+              ...(payload.expectedVersion !== undefined
+                ? { expectedVersion: payload.expectedVersion }
+                : {}),
+              idempotencyKey: payload.idempotencyKey,
+            }),
+          ),
+          payload.expectedVersion === undefined ? 201 : 200,
+        );
+      } catch (error) {
+        throw facetHttpError(error);
+      }
+    },
+  );
+
+  for (const action of ["pause", "resume"] as const) {
+    app.post(
+      `/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey/${action}`,
+      async (c) => {
+        const workspaceId = c.req.param("workspaceId");
+        const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+        const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
+        try {
+          return c.json(
+            IntegrationFacetMutationResult.parse(
+              await setIntegrationFacetLifecycle(deps.db, {
+                accountId: grant.accountId,
+                workspaceId,
+                subjectId: grant.subjectId,
+                capabilityId: decoded(c.req.param("capabilityId")),
+                instanceKey: decoded(c.req.param("instanceKey")),
+                facetKey: decoded(c.req.param("facetKey")),
+                action,
+                expectedVersion: payload.expectedVersion,
+                idempotencyKey: payload.idempotencyKey,
+              }),
+            ),
+          );
+        } catch (error) {
+          throw facetHttpError(error);
+        }
+      },
+    );
+  }
+
+  app.delete(
+    "/v1/workspaces/:workspaceId/integrations/:capabilityId/instances/:instanceKey/facets/:facetKey",
+    async (c) => {
+      const workspaceId = c.req.param("workspaceId");
+      const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+      const payload = MutateIntegrationFacetRequest.parse(await c.req.json());
+      try {
+        return c.json(
+          IntegrationFacetRemovalResult.parse(
+            await removeIntegrationFacet(deps.db, {
+              accountId: grant.accountId,
+              workspaceId,
+              subjectId: grant.subjectId,
+              capabilityId: decoded(c.req.param("capabilityId")),
+              instanceKey: decoded(c.req.param("instanceKey")),
+              facetKey: decoded(c.req.param("facetKey")),
+              expectedVersion: payload.expectedVersion,
+              idempotencyKey: payload.idempotencyKey,
+            }),
+          ),
+        );
+      } catch (error) {
+        throw facetHttpError(error);
+      }
+    },
+  );
+}
+
+function decoded(value: string): string {
+  return decodeURIComponent(value);
+}
+
+function facetHttpError(error: unknown): HTTPException {
+  if (error instanceof HTTPException) return error;
+  if (error instanceof IntegrationFacetNotFoundError) {
+    return new HTTPException(404, { message: error.message });
+  }
+  if (
+    error instanceof IntegrationFacetBindingVersionConflictError ||
+    error instanceof IntegrationFacetBindingVersionRequiredError ||
+    error instanceof IntegrationFacetBindingOwnershipConflictError ||
+    error instanceof IntegrationFacetOperationIdempotencyError
+  ) {
+    return new HTTPException(409, {
+      message:
+        "The Integration facet changed, is shared, or reused an idempotency key. Refresh before retrying.",
+    });
+  }
+  if (
+    error instanceof IntegrationFacetConfigError ||
+    error instanceof IntegrationFacetConnectionError
+  ) {
+    return new HTTPException(422, { message: error.message });
+  }
+  throw error;
+}