bopodev-api 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BopoHQ contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "bopodev-api",
+  "version": "0.1.1",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src",
+    "tsconfig.json"
+  ],
+  "dependencies": {
+    "cors": "^2.8.5",
+    "cron-parser": "^5.3.1",
+    "drizzle-orm": "^0.44.5",
+    "express": "^5.1.0",
+    "nanoid": "^5.1.5",
+    "ws": "^8.19.0",
+    "zod": "^4.1.5",
+    "bopodev-agent-sdk": "0.1.1",
+    "bopodev-contracts": "0.1.1",
+    "bopodev-db": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.3",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.20.5"
+  },
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "start": "tsx src/server.ts",
+    "db:init": "tsx src/scripts/db-init.ts",
+    "build": "tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/app.ts

@@ -0,0 +1,76 @@
+import cors from "cors";
+import express from "express";
+import type { NextFunction, Request, Response } from "express";
+import { sql } from "drizzle-orm";
+import { RepositoryValidationError } from "bopodev-db";
+import { nanoid } from "nanoid";
+import type { AppContext } from "./context";
+import { createAgentsRouter } from "./routes/agents";
+import { createCompaniesRouter } from "./routes/companies";
+import { createGoalsRouter } from "./routes/goals";
+import { createGovernanceRouter } from "./routes/governance";
+import { createHeartbeatRouter } from "./routes/heartbeats";
+import { createIssuesRouter } from "./routes/issues";
+import { createObservabilityRouter } from "./routes/observability";
+import { createProjectsRouter } from "./routes/projects";
+import { sendError } from "./http";
+import { attachRequestActor } from "./middleware/request-actor";
+
+export function createApp(ctx: AppContext) {
+  const app = express();
+  app.use(cors());
+  app.use(express.json());
+  app.use(attachRequestActor);
+
+  app.use((req, res, next) => {
+    const requestId = req.header("x-request-id")?.trim() || nanoid(14);
+    req.requestId = requestId;
+    res.setHeader("x-request-id", requestId);
+    next();
+  });
+
+  app.get("/health", async (_req, res) => {
+    let dbReady = false;
+    let dbError: string | undefined;
+    try {
+      await ctx.db.execute(sql`SELECT 1`);
+      dbReady = true;
+    } catch (error) {
+      dbError = String(error);
+    }
+
+    let runtime = {};
+    try {
+      runtime = (await ctx.getRuntimeHealth?.()) ?? {};
+    } catch (error) {
+      runtime = { error: String(error) };
+    }
+
+    const ok = dbReady;
+    res.status(ok ? 200 : 503).json({
+      ok,
+      db: dbReady ? { ready: true } : { ready: false, error: dbError },
+      runtime
+    });
+  });
+
+  app.use("/companies", createCompaniesRouter(ctx));
+  app.use("/projects", createProjectsRouter(ctx));
+  app.use("/issues", createIssuesRouter(ctx));
+  app.use("/goals", createGoalsRouter(ctx));
+  app.use("/agents", createAgentsRouter(ctx));
+  app.use("/governance", createGovernanceRouter(ctx));
+  app.use("/heartbeats", createHeartbeatRouter(ctx));
+  app.use("/observability", createObservabilityRouter(ctx));
+
+  app.use((error: unknown, _req: Request, res: Response, _next: NextFunction) => {
+    if (error instanceof RepositoryValidationError) {
+      return sendError(res, error.message, 422);
+    }
+    // eslint-disable-next-line no-console
+    console.error(error);
+    return sendError(res, "Internal server error", 500);
+  });
+
+  return app;
+}

package/src/context.ts

@@ -0,0 +1,8 @@
+import type { BopoDb } from "bopodev-db";
+import type { RealtimeHub } from "./realtime/hub";
+
+export interface AppContext {
+  db: BopoDb;
+  getRuntimeHealth?: () => Promise<Record<string, unknown>>;
+  realtimeHub?: RealtimeHub;
+}

package/src/http.ts

@@ -0,0 +1,9 @@
+import type { Response } from "express";
+
+export function sendOk<T>(res: Response, data: T) {
+  return res.status(200).json({ ok: true, data });
+}
+
+export function sendError(res: Response, message: string, code = 400) {
+  return res.status(code).json({ ok: false, error: message });
+}

package/src/middleware/company-scope.ts

@@ -0,0 +1,15 @@
+import type { NextFunction, Request, Response } from "express";
+import { sendError } from "../http";
+import { canAccessCompany } from "./request-actor";
+
+export function requireCompanyScope(req: Request, res: Response, next: NextFunction) {
+  const companyId = req.header("x-company-id") ?? req.query.companyId?.toString();
+  if (!companyId) {
+    return sendError(res, "Missing company scope. Provide x-company-id header.", 422);
+  }
+  if (!canAccessCompany(req, companyId)) {
+    return sendError(res, "Actor does not have access to this company.", 403);
+  }
+  req.companyId = companyId;
+  next();
+}

package/src/middleware/request-actor.ts

@@ -0,0 +1,81 @@
+import type { NextFunction, Request, Response } from "express";
+import { sendError } from "../http";
+
+export type RequestActor = {
+  type: "board" | "member" | "agent";
+  id: string;
+  companyIds: string[] | null;
+  permissions: string[];
+};
+
+declare global {
+  namespace Express {
+    interface Request {
+      actor?: RequestActor;
+      companyId?: string;
+      requestId?: string;
+    }
+  }
+}
+
+export function attachRequestActor(req: Request, _res: Response, next: NextFunction) {
+  const actorTypeHeader = req.header("x-actor-type")?.trim().toLowerCase();
+  const actorType = actorTypeHeader === "agent" || actorTypeHeader === "member" ? actorTypeHeader : "board";
+  const actorId = req.header("x-actor-id")?.trim() || "local-board";
+  const companyIdsHeader = req.header("x-actor-companies")?.trim();
+  const permissionsHeader = req.header("x-actor-permissions")?.trim();
+
+  const companyIds = parseCommaList(companyIdsHeader);
+  const permissions = parseCommaList(permissionsHeader) ?? [];
+
+  req.actor = {
+    type: actorType,
+    id: actorId,
+    companyIds: actorType === "board" ? null : companyIds ?? [],
+    permissions
+  };
+  next();
+}
+
+export function requirePermission(permission: string) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    if (!hasPermission(req, permission)) {
+      return sendError(res, `Missing permission: ${permission}`, 403);
+    }
+    next();
+  };
+}
+
+export function requireBoardRole(req: Request, res: Response, next: NextFunction) {
+  if ((req.actor?.type ?? "board") !== "board") {
+    return sendError(res, "Board role required.", 403);
+  }
+  next();
+}
+
+export function canAccessCompany(req: Request, companyId: string) {
+  const actor = req.actor;
+  if (!actor || actor.type === "board") {
+    return true;
+  }
+  return actor.companyIds?.includes(companyId) ?? false;
+}
+
+function hasPermission(req: Request, permission: string) {
+  const actor = req.actor;
+  if (!actor || actor.type === "board") {
+    return true;
+  }
+  return actor.permissions.includes(permission);
+}
+
+function parseCommaList(value: string | undefined) {
+  if (!value) {
+    return null;
+  }
+  const normalized = value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  return normalized.length > 0 ? normalized : null;
+}

package/src/realtime/governance.ts

@@ -0,0 +1,66 @@
+import type { ApprovalRequest, RealtimeEventEnvelope, RealtimeMessage } from "bopodev-contracts";
+import { listApprovalRequests, type BopoDb } from "bopodev-db";
+
+export async function loadGovernanceRealtimeSnapshot(db: BopoDb, companyId: string): Promise<Extract<RealtimeMessage, { kind: "event" }>> {
+  const approvals = await listApprovalRequests(db, companyId);
+
+  return createRealtimeEvent(companyId, {
+    channel: "governance",
+    event: {
+      type: "approvals.snapshot",
+      approvals: approvals.filter((approval) => approval.status === "pending").map(serializeStoredApproval)
+    }
+  });
+}
+
+export function createGovernanceRealtimeEvent(
+  companyId: string,
+  event: Extract<RealtimeEventEnvelope, { channel: "governance" }>["event"]
+): Extract<RealtimeMessage, { kind: "event" }> {
+  return createRealtimeEvent(companyId, {
+    channel: "governance",
+    event
+  });
+}
+
+export function serializeStoredApproval(approval: {
+  id: string;
+  companyId: string;
+  requestedByAgentId: string | null;
+  action: string;
+  payloadJson: string;
+  status: string;
+  createdAt: Date;
+  resolvedAt: Date | null;
+}): ApprovalRequest {
+  return {
+    id: approval.id,
+    companyId: approval.companyId,
+    requestedByAgentId: approval.requestedByAgentId,
+    action: approval.action as ApprovalRequest["action"],
+    payload: parsePayload(approval.payloadJson),
+    status: approval.status as ApprovalRequest["status"],
+    createdAt: approval.createdAt.toISOString(),
+    resolvedAt: approval.resolvedAt?.toISOString() ?? null
+  };
+}
+
+function createRealtimeEvent(
+  companyId: string,
+  envelope: RealtimeEventEnvelope
+): Extract<RealtimeMessage, { kind: "event" }> {
+  return {
+    kind: "event",
+    companyId,
+    ...envelope
+  };
+}
+
+function parsePayload(payloadJson: string): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(payloadJson) as unknown;
+    return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}

package/src/realtime/hub.ts

@@ -0,0 +1,142 @@
+import type { Server } from "node:http";
+import {
+  RealtimeChannelSchema,
+  type RealtimeChannel,
+  type RealtimeMessage
+} from "bopodev-contracts";
+import { WebSocket, WebSocketServer } from "ws";
+
+type RealtimeEventMessage = Extract<RealtimeMessage, { kind: "event" }>;
+type RealtimeBootstrapLoader = (companyId: string) => Promise<RealtimeEventMessage>;
+
+export interface RealtimeHub {
+  publish(message: RealtimeEventMessage): void;
+  close(): Promise<void>;
+}
+
+export function attachRealtimeHub(
+  server: Server,
+  options: {
+    bootstrapLoaders?: Partial<Record<RealtimeChannel, RealtimeBootstrapLoader>>;
+  } = {}
+): RealtimeHub {
+  const socketsByCompanyAndChannel = new Map<string, Set<WebSocket>>();
+  const wss = new WebSocketServer({ server, path: "/realtime" });
+
+  wss.on("connection", async (socket, request) => {
+    const subscription = getSubscription(request.url);
+    if (!subscription) {
+      socket.close(1008, "Invalid realtime subscription");
+      return;
+    }
+
+    for (const channel of subscription.channels) {
+      addSocket(subscription.companyId, channel, socket);
+    }
+
+    socket.on("close", () => {
+      for (const channel of subscription.channels) {
+        removeSocket(subscription.companyId, channel, socket);
+      }
+    });
+
+    send(socket, {
+      kind: "subscribed",
+      companyId: subscription.companyId,
+      channels: subscription.channels
+    });
+
+    try {
+      for (const channel of subscription.channels) {
+        const loader = options.bootstrapLoaders?.[channel];
+        if (!loader) {
+          continue;
+        }
+        send(socket, await loader(subscription.companyId));
+      }
+    } catch {
+      socket.close(1011, "Failed to load realtime bootstrap");
+    }
+  });
+
+  return {
+    publish(message) {
+      const key = buildSubscriptionKey(message.companyId, message.channel);
+      const sockets = socketsByCompanyAndChannel.get(key);
+      if (!sockets || sockets.size === 0) {
+        return;
+      }
+
+      const payload = JSON.stringify(message);
+      for (const socket of sockets) {
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.send(payload);
+        }
+      }
+    },
+    close() {
+      return new Promise<void>((resolve, reject) => {
+        wss.close((error) => {
+          if (error) {
+            reject(error);
+            return;
+          }
+          resolve();
+        });
+      });
+    }
+  };
+
+  function addSocket(companyId: string, channel: RealtimeChannel, socket: WebSocket) {
+    const key = buildSubscriptionKey(companyId, channel);
+    const sockets = socketsByCompanyAndChannel.get(key) ?? new Set<WebSocket>();
+    sockets.add(socket);
+    socketsByCompanyAndChannel.set(key, sockets);
+  }
+
+  function removeSocket(companyId: string, channel: RealtimeChannel, socket: WebSocket) {
+    const key = buildSubscriptionKey(companyId, channel);
+    const sockets = socketsByCompanyAndChannel.get(key);
+    if (!sockets) {
+      return;
+    }
+    sockets.delete(socket);
+    if (sockets.size === 0) {
+      socketsByCompanyAndChannel.delete(key);
+    }
+  }
+}
+
+function getSubscription(requestUrl: string | undefined) {
+  if (!requestUrl) {
+    return null;
+  }
+
+  const url = new URL(requestUrl, "http://localhost");
+  const companyId = url.searchParams.get("companyId")?.trim();
+  const requestedChannels = url.searchParams.get("channels")?.trim();
+  const channelValues = requestedChannels ? requestedChannels.split(",").map((channel) => channel.trim()).filter(Boolean) : ["governance"];
+  const channels = channelValues.flatMap((channel) => {
+    const parsed = RealtimeChannelSchema.safeParse(channel);
+    return parsed.success ? [parsed.data] : [];
+  });
+
+  if (!companyId || channels.length === 0) {
+    return null;
+  }
+
+  return {
+    companyId,
+    channels: Array.from(new Set(channels))
+  };
+}
+
+function buildSubscriptionKey(companyId: string, channel: RealtimeChannel) {
+  return `${companyId}:${channel}`;
+}
+
+function send(socket: WebSocket, message: RealtimeMessage) {
+  if (socket.readyState === WebSocket.OPEN) {
+    socket.send(JSON.stringify(message));
+  }
+}