Skip to content

Open-source status page, incident response and uptime monitoring

private location: api (#2410)

Thibault Le Ouay70b62eda4cde
diff --git a/.gitignore b/.gitignore
index bc9ce4bf2..8d10b8ce9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -87,3 +87,5 @@ plan.md
skills-lock.json
.mcp.json
+
+tmp
diff --git a/apps/dashboard/src/components/chat/tool-renderers/index.tsx b/apps/dashboard/src/components/chat/tool-renderers/index.tsx
index 66d00ba1d..5c584622b 100644
--- a/apps/dashboard/src/components/chat/tool-renderers/index.tsx
+++ b/apps/dashboard/src/components/chat/tool-renderers/index.tsx
@@ -24,6 +24,7 @@ import { listMaintenancesTable } from "./list-maintenances";
import { listMonitorsTable } from "./list-monitors";
import { listNotificationsTable } from "./list-notifications";
import { listPageComponentsTable } from "./list-page-components";
+import { listPrivateLocationsTable } from "./list-private-locations";
import { listResponseLogsTable } from "./list-response-logs";
import { listStatusPagesTable } from "./list-status-pages";
import { listStatusReportsTable } from "./list-status-reports";
@@ -151,6 +152,12 @@ export const toolRenderers: ToolRendererRegistry = {
),
summary: (o) => itemsCountSummary(o.items),
},
+ list_private_locations: {
+ renderResult: ({ output }) => (
+ <ResultTable {...listPrivateLocationsTable(output)} />
+ ),
+ summary: (o) => itemsCountSummary(o.items),
+ },
list_response_logs: {
renderResult: ({ output }) => (
<ResultTable {...listResponseLogsTable(output)} />
diff --git a/apps/dashboard/src/components/chat/tool-renderers/list-private-locations.tsx b/apps/dashboard/src/components/chat/tool-renderers/list-private-locations.tsx
new file mode 100644
index 000000000..0e4f62770
--- /dev/null
+++ b/apps/dashboard/src/components/chat/tool-renderers/list-private-locations.tsx
@@ -0,0 +1,52 @@
+import type { AgentToolOutput } from "@openstatus/services/agent-tools";
+
+import { TableCellDate } from "@/components/data-table/table-cell-date";
+import { TableCellLink } from "@/components/data-table/table-cell-link";
+import { TableCellNumber } from "@/components/data-table/table-cell-number";
+import { TableCellText } from "@/components/data-table/table-cell-text";
+
+import type { ResultTableData } from "./result-table";
+
+type Output = AgentToolOutput<"list_private_locations">;
+
+export function listPrivateLocationsTable(
+ output: Output,
+): ResultTableData<"name" | "monitors" | "lastSeenAt" | "id"> {
+ const items = output?.items ?? [];
+ return {
+ empty: "No private locations.",
+ columns: [
+ { key: "name", header: "Name" },
+ { key: "monitors", header: "Monitors" },
+ { key: "lastSeenAt", header: "Last seen" },
+ { key: "id", header: "ID" },
+ ],
+ rows: items.map((location) => ({
+ id: location.id,
+ cells: {
+ name: (
+ <TableCellLink
+ href={"/settings/private-locations"}
+ value={location.name}
+ />
+ ),
+ monitors: (
+ <TableCellText
+ value={
+ location.monitorIds.length === 0
+ ? "none"
+ : `${location.monitorIds.length} (${location.monitorIds.join(", ")})`
+ }
+ className="text-muted-foreground font-mono"
+ />
+ ),
+ lastSeenAt: location.lastSeenAt ? (
+ <TableCellDate value={new Date(location.lastSeenAt)} />
+ ) : (
+ <TableCellText value="never" className="text-muted-foreground" />
+ ),
+ id: <TableCellNumber value={location.id} />,
+ },
+ })),
+ };
+}
diff --git a/apps/server/src/routes/mcp/evals/cases.ts b/apps/server/src/routes/mcp/evals/cases.ts
index 6f2e7948b..a3577f8f0 100644
--- a/apps/server/src/routes/mcp/evals/cases.ts
+++ b/apps/server/src/routes/mcp/evals/cases.ts
@@ -150,4 +150,9 @@ export const cases: EvalCase[] = [
"What alerting channels do we have configured? Will anyone get paged if monitor 17 goes down?",
expectedTool: "list_notifications",
},
+ {
+ id: "select.list_private_locations",
+ prompt: "Is our on-prem checker agent still reporting in?",
+ expectedTool: "list_private_locations",
+ },
];
diff --git a/apps/server/src/routes/mcp/handler.test.ts b/apps/server/src/routes/mcp/handler.test.ts
index 46ba666c2..fbffb4af3 100644
--- a/apps/server/src/routes/mcp/handler.test.ts
+++ b/apps/server/src/routes/mcp/handler.test.ts
@@ -97,6 +97,7 @@ describe("MCP transport", () => {
"list_monitors",
"list_notifications",
"list_page_components",
+ "list_private_locations",
"list_response_logs",
"list_status_pages",
"list_status_reports",
diff --git a/apps/server/src/routes/mcp/server.ts b/apps/server/src/routes/mcp/server.ts
index 91a873f70..280850c25 100644
--- a/apps/server/src/routes/mcp/server.ts
+++ b/apps/server/src/routes/mcp/server.ts
@@ -7,6 +7,7 @@ import { registerMaintenanceTools } from "./tools/maintenance";
import { registerMonitorTools } from "./tools/monitor";
import { registerNotificationTools } from "./tools/notification";
import { registerPageTools } from "./tools/page";
+import { registerPrivateLocationTools } from "./tools/private-location";
import { registerStatusReportTools } from "./tools/status-report";
/**
@@ -29,6 +30,7 @@ export function createMcpServer(ctx: ServiceContext): McpServer {
registerMaintenanceTools(server, ctx);
registerMonitorTools(server, ctx);
registerNotificationTools(server, ctx);
+ registerPrivateLocationTools(server, ctx);
registerAuditTools(server, ctx);
return server;
}
diff --git a/apps/server/src/routes/mcp/tools/private-location.ts b/apps/server/src/routes/mcp/tools/private-location.ts
new file mode 100644
index 000000000..59354de3c
--- /dev/null
+++ b/apps/server/src/routes/mcp/tools/private-location.ts
@@ -0,0 +1,15 @@
+import type {
+ McpServer,
+ RegisteredTool,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ServiceContext } from "@openstatus/services";
+import { listPrivateLocationsTool } from "@openstatus/services/agent-tools";
+
+import { registerRegistryTools } from "./registry-adapter";
+
+export function registerPrivateLocationTools(
+ server: McpServer,
+ ctx: ServiceContext,
+): Map<string, RegisteredTool> {
+ return registerRegistryTools(server, ctx, [listPrivateLocationsTool]);
+}
diff --git a/apps/server/src/routes/mcp/tools/tools.test.ts b/apps/server/src/routes/mcp/tools/tools.test.ts
index 3e4e82b3a..34e5bde65 100644
--- a/apps/server/src/routes/mcp/tools/tools.test.ts
+++ b/apps/server/src/routes/mcp/tools/tools.test.ts
@@ -4,6 +4,7 @@ import {
page,
pageComponent,
pageSubscriber,
+ privateLocation,
statusReport,
statusReportUpdate,
} from "@openstatus/db/src/schema";
@@ -25,6 +26,7 @@ import { afterAll, beforeAll, describe, test } from "@std/testing/bdd";
import { toServiceCtx } from "../adapter";
import { registerMaintenanceTools } from "./maintenance";
import { registerPageTools } from "./page";
+import { registerPrivateLocationTools } from "./private-location";
import { registerStatusReportTools } from "./status-report";
/**
@@ -107,7 +109,7 @@ afterAll(async () => {
/** Build a fresh McpServer + register a tool group, return the tool map. */
function registered(
- group: "page" | "status-report" | "maintenance",
+ group: "page" | "status-report" | "maintenance" | "private-location",
ctx: ServiceContext,
) {
const server = new McpServer(
@@ -121,6 +123,8 @@ function registered(
return registerStatusReportTools(server, ctx);
case "maintenance":
return registerMaintenanceTools(server, ctx);
+ case "private-location":
+ return registerPrivateLocationTools(server, ctx);
}
}
@@ -581,6 +585,55 @@ describe("create_maintenance", () => {
});
});
+describe("list_private_locations", () => {
+ test("never exposes the agent token", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = makeMcpToolCtx(teamWorkspace, { db: tx });
+ await tx.insert(privateLocation).values({
+ name: `${TEST_PREFIX}-mcp-location`,
+ token: "super-secret-agent-token",
+ workspaceId: teamWorkspace.id,
+ });
+
+ const tools = registered("private-location", ctx);
+ const result = await callTool(tools, "list_private_locations", {
+ page: 1,
+ perPage: 50,
+ });
+
+ expect(result.isError).toBeFalsy();
+
+ const serialized = JSON.stringify(result);
+ expect(serialized).not.toContain("super-secret-agent-token");
+ expect(serialized).not.toContain("token");
+ });
+ });
+
+ test("returns locations for the workspace", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = makeMcpToolCtx(teamWorkspace, { db: tx });
+ await tx.insert(privateLocation).values({
+ name: `${TEST_PREFIX}-mcp-listed`,
+ token: "another-token",
+ workspaceId: teamWorkspace.id,
+ });
+
+ const tools = registered("private-location", ctx);
+ const result = await callTool(tools, "list_private_locations", {
+ page: 1,
+ perPage: 50,
+ });
+
+ const structured = result.structuredContent as {
+ items: { name: string }[];
+ };
+ expect(structured.items.some((i) => i.name.includes("mcp-listed"))).toBe(
+ true,
+ );
+ });
+ });
+});
+
describe("scope filter", () => {
test("read-only key sees read tools, no write tools", async () => {
const ctx = makeMcpToolCtx(teamWorkspace, { scopes: ["read"] });
@@ -592,6 +645,9 @@ describe("scope filter", () => {
expect(pageTools.has("list_status_pages")).toBe(true);
expect(reportTools.has("list_status_reports")).toBe(true);
expect(maintenanceTools.has("list_maintenances")).toBe(true);
+ expect(
+ registered("private-location", ctx).has("list_private_locations"),
+ ).toBe(true);
// Write tools must be filtered out — registry doesn't carry them
// and `tools/list` will see only the read tools.
diff --git a/apps/server/src/routes/rpc/handlers/private-location/__tests__/private-location.test.ts b/apps/server/src/routes/rpc/handlers/private-location/__tests__/private-location.test.ts
new file mode 100644
index 000000000..b9ac28664
--- /dev/null
+++ b/apps/server/src/routes/rpc/handlers/private-location/__tests__/private-location.test.ts
@@ -0,0 +1,609 @@
+import { db, eq } from "@openstatus/db";
+import {
+ monitor,
+ privateLocation,
+ privateLocationToMonitors,
+ workspace,
+} from "@openstatus/db/src/schema";
+import { getLimits } from "@openstatus/db/src/schema/plan/utils";
+import { expect } from "@std/expect";
+import { afterAll, beforeAll, describe, test } from "@std/testing/bdd";
+import { nanoid } from "nanoid";
+
+import { app } from "../../../../../index";
+
+async function connectRequest(
+ method: string,
+ body: Record<string, unknown> = {},
+ headers: Record<string, string> = {},
+) {
+ return app.request(
+ `/rpc/openstatus.private_location.v1.PrivateLocationService/${method}`,
+ {
+ method: "POST",
+ headers: { "Content-Type": "application/json", ...headers },
+ body: JSON.stringify(body),
+ },
+ );
+}
+
+const TEST_PREFIX = "rpc-private-location-test";
+
+// Scoped to a dedicated workspace so parallel suites mutating the shared seed
+// workspace can't delete our fixtures mid-run. In test, `validateKey` maps
+// `x-openstatus-key` to the workspace id.
+let entitledWorkspaceId: number;
+let authKey: string;
+let freeWorkspaceId: number;
+let freeAuthKey: string;
+
+let testMonitorId: number;
+let secondMonitorId: number;
+let deletedMonitorId: number;
+let foreignMonitorId: number;
+
+let testLocationId: number;
+let locationToUpdateId: number;
+let locationToDeleteId: number;
+
+const mkWorkspace = async (
+ plan: "team" | "free",
+ privateLocations: boolean,
+) => {
+ const limits = { ...getLimits(plan), "private-locations": privateLocations };
+ const row = await db
+ .insert(workspace)
+ .values({
+ slug: `${TEST_PREFIX}-ws-${nanoid(8)}`,
+ name: `${TEST_PREFIX}-workspace`,
+ plan,
+ limits: JSON.stringify(limits),
+ })
+ .returning()
+ .get();
+ return row.id;
+};
+
+const mkMonitor = async (
+ name: string,
+ workspaceId: number,
+ deleted?: boolean,
+) => {
+ const row = await db
+ .insert(monitor)
+ .values({
+ name,
+ workspaceId,
+ url: "https://example.com",
+ periodicity: "10m",
+ deletedAt: deleted ? new Date() : null,
+ })
+ .returning()
+ .get();
+ return row.id;
+};
+
+const mkLocation = async (name: string, workspaceId: number) => {
+ const row = await db
+ .insert(privateLocation)
+ .values({ name, token: `token-${nanoid(8)}`, workspaceId })
+ .returning()
+ .get();
+ return row.id;
+};
+
+beforeAll(async () => {
+ entitledWorkspaceId = await mkWorkspace("team", true);
+ authKey = String(entitledWorkspaceId);
+
+ freeWorkspaceId = await mkWorkspace("free", false);
+ freeAuthKey = String(freeWorkspaceId);
+
+ testMonitorId = await mkMonitor(
+ `${TEST_PREFIX}-monitor`,
+ entitledWorkspaceId,
+ );
+ secondMonitorId = await mkMonitor(
+ `${TEST_PREFIX}-monitor-2`,
+ entitledWorkspaceId,
+ );
+ deletedMonitorId = await mkMonitor(
+ `${TEST_PREFIX}-monitor-deleted`,
+ entitledWorkspaceId,
+ true,
+ );
+ foreignMonitorId = await mkMonitor(
+ `${TEST_PREFIX}-monitor-foreign`,
+ freeWorkspaceId,
+ );
+
+ testLocationId = await mkLocation(`${TEST_PREFIX}-main`, entitledWorkspaceId);
+ await db
+ .insert(privateLocationToMonitors)
+ .values({ privateLocationId: testLocationId, monitorId: testMonitorId });
+
+ locationToUpdateId = await mkLocation(
+ `${TEST_PREFIX}-to-update`,
+ entitledWorkspaceId,
+ );
+ await db.insert(privateLocationToMonitors).values({
+ privateLocationId: locationToUpdateId,
+ monitorId: testMonitorId,
+ });
+
+ locationToDeleteId = await mkLocation(
+ `${TEST_PREFIX}-to-delete`,
+ entitledWorkspaceId,
+ );
+});
+
+afterAll(async () => {
+ for (const id of [entitledWorkspaceId, freeWorkspaceId]) {
+ await db.delete(privateLocation).where(eq(privateLocation.workspaceId, id));
+ await db.delete(monitor).where(eq(monitor.workspaceId, id));
+ await db.delete(workspace).where(eq(workspace.id, id));
+ }
+});
+
+describe("PrivateLocationService.CreatePrivateLocation", () => {
+ test("creates a private location with a server-generated token", async () => {
+ const res = await connectRequest(
+ "CreatePrivateLocation",
+ {
+ name: `${TEST_PREFIX}-created`,
+ monitorIds: [String(testMonitorId)],
+ },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data).toHaveProperty("privateLocation");
+ expect(data.privateLocation.name).toBe(`${TEST_PREFIX}-created`);
+ expect(data.privateLocation.token).toBeTruthy();
+ expect(data.privateLocation.monitorIds).toContain(String(testMonitorId));
+
+ await db
+ .delete(privateLocation)
+ .where(eq(privateLocation.id, Number(data.privateLocation.id)));
+ });
+
+ test("generates a distinct token per location", async () => {
+ const mk = async (name: string) => {
+ const res = await connectRequest(
+ "CreatePrivateLocation",
+ { name },
+ { "x-openstatus-key": authKey },
+ );
+ expect(res.status).toBe(200);
+ return await res.json();
+ };
+
+ const a = await mk(`${TEST_PREFIX}-token-a`);
+ const b = await mk(`${TEST_PREFIX}-token-b`);
+
+ expect(a.privateLocation.token).not.toBe(b.privateLocation.token);
+
+ for (const data of [a, b]) {
+ await db
+ .delete(privateLocation)
+ .where(eq(privateLocation.id, Number(data.privateLocation.id)));
+ }
+ });
+
+ test("ignores a caller-supplied token", async () => {
+ const res = await connectRequest(
+ "CreatePrivateLocation",
+ { name: `${TEST_PREFIX}-ignores-token`, token: "attacker-chosen" },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+ const data = await res.json();
+ expect(data.privateLocation.token).not.toBe("attacker-chosen");
+
+ await db
+ .delete(privateLocation)
+ .where(eq(privateLocation.id, Number(data.privateLocation.id)));
+ });
+
+ test("returns 403 for a workspace without the entitlement", async () => {
+ const res = await connectRequest(
+ "CreatePrivateLocation",
+ { name: `${TEST_PREFIX}-not-entitled` },
+ { "x-openstatus-key": freeAuthKey },
+ );
+
+ expect(res.status).toBe(403);
+ });
+
+ test("returns 403 for a monitor in another workspace", async () => {
+ const res = await connectRequest(
+ "CreatePrivateLocation",
+ {
+ name: `${TEST_PREFIX}-foreign-monitor`,
+ monitorIds: [String(foreignMonitorId)],
+ },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(403);
+ });
+
+ test("returns 403 for a soft-deleted monitor", async () => {
+ const res = await connectRequest(
+ "CreatePrivateLocation",
+ {
+ name: `${TEST_PREFIX}-deleted-monitor`,
+ monitorIds: [String(deletedMonitorId)],
+ },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(403);
+ });
+
+ test("returns 400 when name is empty", async () => {
+ const res = await connectRequest(
+ "CreatePrivateLocation",
+ { name: "" },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(400);
+ });
+
+ test("returns 401 when no auth key provided", async () => {
+ const res = await connectRequest("CreatePrivateLocation", {
+ name: `${TEST_PREFIX}-unauth`,
+ });
+
+ expect(res.status).toBe(401);
+ });
+});
+
+describe("PrivateLocationService.GetPrivateLocation", () => {
+ test("returns the location including its token", async () => {
+ const res = await connectRequest(
+ "GetPrivateLocation",
+ { id: String(testLocationId) },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.privateLocation.id).toBe(String(testLocationId));
+ expect(data.privateLocation.name).toBe(`${TEST_PREFIX}-main`);
+ expect(data.privateLocation.token).toBeTruthy();
+ expect(data.privateLocation.monitorIds).toContain(String(testMonitorId));
+ expect(data.privateLocation.createdAt).toBeTruthy();
+ });
+
+ test("returns 404 for a non-existent id", async () => {
+ const res = await connectRequest(
+ "GetPrivateLocation",
+ { id: "99999999" },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(404);
+ expect(res.headers.get("error-reason")).toBe("PRIVATE_LOCATION_NOT_FOUND");
+ });
+
+ test("returns 404 for a location in another workspace", async () => {
+ const foreignId = await mkLocation(
+ `${TEST_PREFIX}-foreign`,
+ freeWorkspaceId,
+ );
+
+ const res = await connectRequest(
+ "GetPrivateLocation",
+ { id: String(foreignId) },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(404);
+
+ await db.delete(privateLocation).where(eq(privateLocation.id, foreignId));
+ });
+
+ test("returns 400 when id is empty", async () => {
+ const res = await connectRequest(
+ "GetPrivateLocation",
+ { id: "" },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(400);
+ });
+
+ test("returns 401 when no auth key provided", async () => {
+ const res = await connectRequest("GetPrivateLocation", {
+ id: String(testLocationId),
+ });
+
+ expect(res.status).toBe(401);
+ });
+});
+
+describe("PrivateLocationService.ListPrivateLocations", () => {
+ test("returns workspace-scoped summaries without tokens", async () => {
+ const res = await connectRequest(
+ "ListPrivateLocations",
+ {},
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(Array.isArray(data.privateLocations)).toBe(true);
+ expect(data.totalSize).toBeGreaterThan(0);
+
+ for (const summary of data.privateLocations) {
+ expect(summary.token).toBeUndefined();
+ }
+
+ const ids = data.privateLocations.map(
+ (l: { id: string }) => l.id,
+ ) as string[];
+ expect(ids).toContain(String(testLocationId));
+ });
+
+ test("reports monitorCount for an attached location", async () => {
+ const res = await connectRequest(
+ "ListPrivateLocations",
+ {},
+ { "x-openstatus-key": authKey },
+ );
+
+ const data = await res.json();
+ const found = data.privateLocations.find(
+ (l: { id: string; monitorCount?: number }) =>
+ l.id === String(testLocationId),
+ );
+ expect(found.monitorCount).toBe(1);
+ });
+
+ test("applies limit and offset", async () => {
+ const first = await connectRequest(
+ "ListPrivateLocations",
+ { limit: 1, offset: 0 },
+ { "x-openstatus-key": authKey },
+ );
+ const second = await connectRequest(
+ "ListPrivateLocations",
+ { limit: 1, offset: 1 },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(first.status).toBe(200);
+ expect(second.status).toBe(200);
+
+ const firstData = await first.json();
+ const secondData = await second.json();
+ expect(firstData.privateLocations.length).toBe(1);
+ expect(secondData.privateLocations.length).toBe(1);
+ expect(firstData.privateLocations[0].id).not.toBe(
+ secondData.privateLocations[0].id,
+ );
+ });
+
+ test("returns 400 when limit exceeds the maximum", async () => {
+ const res = await connectRequest(
+ "ListPrivateLocations",
+ { limit: 500 },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(400);
+ });
+
+ test("returns 401 when no auth key provided", async () => {
+ const res = await connectRequest("ListPrivateLocations", {});
+ expect(res.status).toBe(401);
+ });
+});
+
+describe("PrivateLocationService.UpdatePrivateLocation", () => {
+ test("updates the name and leaves associations untouched", async () => {
+ const res = await connectRequest(
+ "UpdatePrivateLocation",
+ { id: String(locationToUpdateId), name: `${TEST_PREFIX}-renamed` },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.privateLocation.name).toBe(`${TEST_PREFIX}-renamed`);
+ expect(data.privateLocation.monitorIds).toEqual([String(testMonitorId)]);
+ });
+
+ test("ignores monitorIds when updateMonitorIds is absent", async () => {
+ const res = await connectRequest(
+ "UpdatePrivateLocation",
+ {
+ id: String(locationToUpdateId),
+ monitorIds: [String(secondMonitorId)],
+ },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.privateLocation.monitorIds).toEqual([String(testMonitorId)]);
+ });
+
+ test("replaces associations when updateMonitorIds is true", async () => {
+ const target = await mkLocation(
+ `${TEST_PREFIX}-replace`,
+ entitledWorkspaceId,
+ );
+ await db
+ .insert(privateLocationToMonitors)
+ .values({ privateLocationId: target, monitorId: testMonitorId });
+
+ const res = await connectRequest(
+ "UpdatePrivateLocation",
+ {
+ id: String(target),
+ monitorIds: [String(secondMonitorId)],
+ updateMonitorIds: true,
+ },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.privateLocation.monitorIds).toEqual([String(secondMonitorId)]);
+
+ await db.delete(privateLocation).where(eq(privateLocation.id, target));
+ });
+
+ test("clears associations with an empty list and the flag set", async () => {
+ const target = await mkLocation(
+ `${TEST_PREFIX}-clear`,
+ entitledWorkspaceId,
+ );
+ await db
+ .insert(privateLocationToMonitors)
+ .values({ privateLocationId: target, monitorId: testMonitorId });
+
+ const res = await connectRequest(
+ "UpdatePrivateLocation",
+ { id: String(target), monitorIds: [], updateMonitorIds: true },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.privateLocation.monitorIds ?? []).toEqual([]);
+
+ await db.delete(privateLocation).where(eq(privateLocation.id, target));
+ });
+
+ test("returns 403 for a workspace without the entitlement", async () => {
+ const res = await connectRequest(
+ "UpdatePrivateLocation",
+ { id: String(testLocationId), name: "nope" },
+ { "x-openstatus-key": freeAuthKey },
+ );
+
+ expect(res.status).toBe(403);
+ });
+
+ test("returns 404 for a non-existent id", async () => {
+ const res = await connectRequest(
+ "UpdatePrivateLocation",
+ { id: "99999999", name: "nope" },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(404);
+ });
+
+ test("returns 401 when no auth key provided", async () => {
+ const res = await connectRequest("UpdatePrivateLocation", {
+ id: String(testLocationId),
+ name: "nope",
+ });
+
+ expect(res.status).toBe(401);
+ });
+});
+
+describe("PrivateLocationService.DeletePrivateLocation", () => {
+ test("deletes the location and cascades its links", async () => {
+ const res = await connectRequest(
+ "DeletePrivateLocation",
+ { id: String(locationToDeleteId) },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const data = await res.json();
+ expect(data.success).toBe(true);
+
+ const remaining = await db
+ .select()
+ .from(privateLocation)
+ .where(eq(privateLocation.id, locationToDeleteId))
+ .all();
+ expect(remaining.length).toBe(0);
+
+ const links = await db
+ .select()
+ .from(privateLocationToMonitors)
+ .where(
+ eq(privateLocationToMonitors.privateLocationId, locationToDeleteId),
+ )
+ .all();
+ expect(links.length).toBe(0);
+ });
+
+ test("is idempotent for a non-existent id", async () => {
+ const res = await connectRequest(
+ "DeletePrivateLocation",
+ { id: "99999999" },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+ const data = await res.json();
+ expect(data.success).toBe(true);
+ });
+
+ test("succeeds for a workspace without the entitlement", async () => {
+ const target = await mkLocation(
+ `${TEST_PREFIX}-free-delete`,
+ freeWorkspaceId,
+ );
+
+ const res = await connectRequest(
+ "DeletePrivateLocation",
+ { id: String(target) },
+ { "x-openstatus-key": freeAuthKey },
+ );
+
+ expect(res.status).toBe(200);
+ });
+
+ test("does not delete another workspace's location", async () => {
+ const foreignId = await mkLocation(
+ `${TEST_PREFIX}-foreign-delete`,
+ freeWorkspaceId,
+ );
+
+ const res = await connectRequest(
+ "DeletePrivateLocation",
+ { id: String(foreignId) },
+ { "x-openstatus-key": authKey },
+ );
+
+ expect(res.status).toBe(200);
+
+ const remaining = await db
+ .select()
+ .from(privateLocation)
+ .where(eq(privateLocation.id, foreignId))
+ .all();
+ expect(remaining.length).toBe(1);
+
+ await db.delete(privateLocation).where(eq(privateLocation.id, foreignId));
+ });
+
+ test("returns 401 when no auth key provided", async () => {
+ const res = await connectRequest("DeletePrivateLocation", {
+ id: String(testLocationId),
+ });
+
+ expect(res.status).toBe(401);
+ });
+});
diff --git a/apps/server/src/routes/rpc/handlers/private-location/converters.ts b/apps/server/src/routes/rpc/handlers/private-location/converters.ts
new file mode 100644
index 000000000..70555f90b
--- /dev/null
+++ b/apps/server/src/routes/rpc/handlers/private-location/converters.ts
@@ -0,0 +1,45 @@
+import type {
+ PrivateLocation,
+ PrivateLocationSummary,
+} from "@openstatus/proto/private_location/v1";
+
+type DBPrivateLocation = {
+ id: number;
+ name: string;
+ token: string;
+ lastSeenAt: Date | null;
+ createdAt: Date | null;
+ updatedAt: Date | null;
+};
+
+export function dbPrivateLocationToProto(
+ location: DBPrivateLocation,
+ monitorIds: string[],
+): PrivateLocation {
+ return {
+ $typeName: "openstatus.private_location.v1.PrivateLocation" as const,
+ id: String(location.id),
+ name: location.name,
+ token: location.token,
+ monitorIds,
+ lastSeenAt: location.lastSeenAt?.toISOString() ?? "",
+ createdAt: location.createdAt?.toISOString() ?? "",
+ updatedAt: location.updatedAt?.toISOString() ?? "",
+ };
+}
+
+/** The agent token is deliberately absent — list responses must not leak it. */
+export function dbPrivateLocationToProtoSummary(
+ location: DBPrivateLocation,
+ monitorCount: number,
+): PrivateLocationSummary {
+ return {
+ $typeName: "openstatus.private_location.v1.PrivateLocationSummary" as const,
+ id: String(location.id),
+ name: location.name,
+ monitorCount,
+ lastSeenAt: location.lastSeenAt?.toISOString() ?? "",
+ createdAt: location.createdAt?.toISOString() ?? "",
+ updatedAt: location.updatedAt?.toISOString() ?? "",
+ };
+}
diff --git a/apps/server/src/routes/rpc/handlers/private-location/errors.ts b/apps/server/src/routes/rpc/handlers/private-location/errors.ts
new file mode 100644
index 000000000..612981bbe
--- /dev/null
+++ b/apps/server/src/routes/rpc/handlers/private-location/errors.ts
@@ -0,0 +1,59 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+
+export const ErrorReason = {
+ PRIVATE_LOCATION_NOT_FOUND: "PRIVATE_LOCATION_NOT_FOUND",
+ PRIVATE_LOCATION_ID_REQUIRED: "PRIVATE_LOCATION_ID_REQUIRED",
+ INVALID_MONITOR_ID: "INVALID_MONITOR_ID",
+} as const;
+
+export type ErrorReason = (typeof ErrorReason)[keyof typeof ErrorReason];
+
+const DOMAIN = "openstatus.dev";
+
+function createError(
+ message: string,
+ code: Code,
+ reason: ErrorReason,
+ metadata?: Record<string, string>,
+): ConnectError {
+ const headers = new Headers({
+ "error-domain": DOMAIN,
+ "error-reason": reason,
+ });
+
+ if (metadata) {
+ for (const [key, value] of Object.entries(metadata)) {
+ headers.set(`error-${key}`, value);
+ }
+ }
+
+ return new ConnectError(message, code, headers);
+}
+
+export function privateLocationNotFoundError(
+ privateLocationId: string,
+): ConnectError {
+ return createError(
+ "Private location not found",
+ Code.NotFound,
+ ErrorReason.PRIVATE_LOCATION_NOT_FOUND,
+ { "private-location-id": privateLocationId },
+ );
+}
+
+export function privateLocationIdRequiredError(): ConnectError {
+ return createError(
+ "Private location ID is required",
+ Code.InvalidArgument,
+ ErrorReason.PRIVATE_LOCATION_ID_REQUIRED,
+ );
+}
+
+export function invalidMonitorIdError(monitorId: string): ConnectError {
+ return createError(
+ `Invalid monitor id: "${monitorId}"`,
+ Code.InvalidArgument,
+ ErrorReason.INVALID_MONITOR_ID,
+ { "monitor-id": monitorId },
+ );
+}
diff --git a/apps/server/src/routes/rpc/handlers/private-location/index.ts b/apps/server/src/routes/rpc/handlers/private-location/index.ts
new file mode 100644
index 000000000..b2e7df351
--- /dev/null
+++ b/apps/server/src/routes/rpc/handlers/private-location/index.ts
@@ -0,0 +1,176 @@
+import type { ServiceImpl } from "@connectrpc/connect";
+import type { PrivateLocationService } from "@openstatus/proto/private_location/v1";
+import { NotFoundError } from "@openstatus/services";
+import {
+ createPrivateLocation,
+ deletePrivateLocation,
+ getPrivateLocation,
+ listPrivateLocations,
+ updatePrivateLocation,
+} from "@openstatus/services/private-location";
+
+import { toConnectError, toServiceCtx } from "../../adapter";
+import { getRpcContext } from "../../interceptors";
+import {
+ dbPrivateLocationToProto,
+ dbPrivateLocationToProtoSummary,
+} from "./converters";
+import {
+ invalidMonitorIdError,
+ privateLocationIdRequiredError,
+ privateLocationNotFoundError,
+} from "./errors";
+import { checkPrivateLocationsEnabled } from "./limits";
+
+// Map the service's generic NotFoundError to a ConnectError carrying the
+// documented error-reason header for this entity, then defer everything else
+// to the shared mapper.
+function toPrivateLocationConnectError(err: unknown, id: string): never {
+ if (err instanceof NotFoundError && err.entity === "private_location") {
+ throw privateLocationNotFoundError(id);
+ }
+ toConnectError(err);
+}
+
+// `Number.parseInt` rather than `Number` — `Number("")` is 0 (finite!), which
+// would silently target row 0 instead of failing.
+function parseId(id: string): number {
+ const n = Number.parseInt(id, 10);
+ if (!Number.isFinite(n)) throw privateLocationIdRequiredError();
+ return n;
+}
+
+function parseMonitorIds(ids: ReadonlyArray<string>): number[] {
+ return ids.map((id) => {
+ const n = Number.parseInt(id, 10);
+ if (!Number.isFinite(n)) throw invalidMonitorIdError(id);
+ return n;
+ });
+}
+
+function requireId(id: string): number {
+ if (!id || id.trim() === "") throw privateLocationIdRequiredError();
+ return parseId(id);
+}
+
+export const privateLocationServiceImpl: ServiceImpl<
+ typeof PrivateLocationService
+> = {
+ async createPrivateLocation(req, ctx) {
+ try {
+ const rpcCtx = getRpcContext(ctx);
+ checkPrivateLocationsEnabled(rpcCtx.workspace.limits);
+ const sCtx = toServiceCtx(rpcCtx);
+
+ const created = await createPrivateLocation({
+ ctx: sCtx,
+ input: {
+ name: req.name,
+ monitors: parseMonitorIds(req.monitorIds),
+ },
+ });
+
+ // Re-fetch so the response reflects stored ids (deduped), not the request.
+ const full = await getPrivateLocation({
+ ctx: sCtx,
+ input: { id: created.id },
+ });
+
+ return {
+ privateLocation: dbPrivateLocationToProto(
+ full,
+ full.monitors.map((m) => String(m.id)),
+ ),
+ };
+ } catch (err) {
+ toConnectError(err);
+ }
+ },
+
+ async getPrivateLocation(req, ctx) {
+ try {
+ const rpcCtx = getRpcContext(ctx);
+ const full = await getPrivateLocation({
+ ctx: toServiceCtx(rpcCtx),
+ input: { id: requireId(req.id) },
+ });
+
+ return {
+ privateLocation: dbPrivateLocationToProto(
+ full,
+ full.monitors.map((m) => String(m.id)),
+ ),
+ };
+ } catch (err) {
+ toPrivateLocationConnectError(err, req.id);
+ }
+ },
+
+ async listPrivateLocations(req, ctx) {
+ try {
+ const rpcCtx = getRpcContext(ctx);
+
+ const { items, totalSize } = await listPrivateLocations({
+ ctx: toServiceCtx(rpcCtx),
+ input: {
+ limit: Math.min(Math.max(req.limit ?? 50, 1), 100),
+ offset: req.offset ?? 0,
+ },
+ });
+
+ return {
+ privateLocations: items.map((item) =>
+ dbPrivateLocationToProtoSummary(item, item.monitors.length),
+ ),
+ totalSize,
+ };
+ } catch (err) {
+ toConnectError(err);
+ }
+ },
+
+ async updatePrivateLocation(req, ctx) {
+ try {
+ const rpcCtx = getRpcContext(ctx);
+ checkPrivateLocationsEnabled(rpcCtx.workspace.limits);
+ const sCtx = toServiceCtx(rpcCtx);
+ const id = requireId(req.id);
+
+ await updatePrivateLocation({
+ ctx: sCtx,
+ input: {
+ id,
+ name:
+ req.name !== undefined && req.name !== "" ? req.name : undefined,
+ monitors: req.updateMonitorIds
+ ? parseMonitorIds(req.monitorIds)
+ : undefined,
+ },
+ });
+
+ const full = await getPrivateLocation({ ctx: sCtx, input: { id } });
+
+ return {
+ privateLocation: dbPrivateLocationToProto(
+ full,
+ full.monitors.map((m) => String(m.id)),
+ ),
+ };
+ } catch (err) {
+ toPrivateLocationConnectError(err, req.id);
+ }
+ },
+
+ async deletePrivateLocation(req, ctx) {
+ try {
+ const rpcCtx = getRpcContext(ctx);
+ await deletePrivateLocation({
+ ctx: toServiceCtx(rpcCtx),
+ input: { id: requireId(req.id) },
+ });
+ return { success: true };
+ } catch (err) {
+ toConnectError(err);
+ }
+ },
+};
diff --git a/apps/server/src/routes/rpc/handlers/private-location/limits.ts b/apps/server/src/routes/rpc/handlers/private-location/limits.ts
new file mode 100644
index 000000000..81fec25d0
--- /dev/null
+++ b/apps/server/src/routes/rpc/handlers/private-location/limits.ts
@@ -0,0 +1,15 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { Limits } from "@openstatus/db/src/schema/plan/schema";
+
+/**
+ * `private-locations` is a boolean entitlement, not a row-count cap — there is
+ * no per-workspace limit on how many agents a paid plan may register.
+ */
+export function checkPrivateLocationsEnabled(limits: Limits): void {
+ if (!limits["private-locations"]) {
+ throw new ConnectError(
+ "Upgrade to use private locations",
+ Code.PermissionDenied,
+ );
+ }
+}
diff --git a/apps/server/src/routes/rpc/interceptors/tracking.ts b/apps/server/src/routes/rpc/interceptors/tracking.ts
index b49a50551..0cb8794f3 100644
--- a/apps/server/src/routes/rpc/interceptors/tracking.ts
+++ b/apps/server/src/routes/rpc/interceptors/tracking.ts
@@ -99,6 +99,20 @@ export const RPC_EVENT_MAP: Record<string, RpcEventMapping> = {
"openstatus.notification.v1.NotificationService/DeleteNotification": {
event: Events.DeleteNotification,
},
+
+ // PrivateLocationService
+ "openstatus.private_location.v1.PrivateLocationService/CreatePrivateLocation":
+ {
+ event: Events.CreatePrivateLocation,
+ },
+ "openstatus.private_location.v1.PrivateLocationService/UpdatePrivateLocation":
+ {
+ event: Events.UpdatePrivateLocation,
+ },
+ "openstatus.private_location.v1.PrivateLocationService/DeletePrivateLocation":
+ {
+ event: Events.DeletePrivateLocation,
+ },
};
/**
diff --git a/apps/server/src/routes/rpc/router.ts b/apps/server/src/routes/rpc/router.ts
index 203ece040..6233edaa4 100644
--- a/apps/server/src/routes/rpc/router.ts
+++ b/apps/server/src/routes/rpc/router.ts
@@ -3,6 +3,7 @@ import { HealthService } from "@openstatus/proto/health/v1";
import { MaintenanceService } from "@openstatus/proto/maintenance/v1";
import { MonitorService } from "@openstatus/proto/monitor/v1";
import { NotificationService } from "@openstatus/proto/notification/v1";
+import { PrivateLocationService } from "@openstatus/proto/private_location/v1";
import { StatusPageService } from "@openstatus/proto/status_page/v1";
import { StatusReportService } from "@openstatus/proto/status_report/v1";
@@ -10,6 +11,7 @@ import { healthServiceImpl } from "./handlers/health";
import { maintenanceServiceImpl } from "./handlers/maintenance";
import { monitorServiceImpl } from "./handlers/monitor";
import { notificationServiceImpl } from "./handlers/notification";
+import { privateLocationServiceImpl } from "./handlers/private-location";
import { statusPageServiceImpl } from "./handlers/status-page";
import { statusReportServiceImpl } from "./handlers/status-report";
import {
@@ -43,4 +45,5 @@ export const routes = createConnectRouter({
.service(StatusReportService, statusReportServiceImpl)
.service(StatusPageService, statusPageServiceImpl)
.service(MaintenanceService, maintenanceServiceImpl)
- .service(NotificationService, notificationServiceImpl);
+ .service(NotificationService, notificationServiceImpl)
+ .service(PrivateLocationService, privateLocationServiceImpl);
diff --git a/apps/server/static/openapi.yaml b/apps/server/static/openapi.yaml
index 9ad73d881..324d1369a 100644
--- a/apps/server/static/openapi.yaml
+++ b/apps/server/static/openapi.yaml
@@ -2325,6 +2325,233 @@ components:
title: WhatsappData
additionalProperties: false
description: WhatsappData contains configuration for WhatsApp notifications.
+ openstatus.private_location.v1.CreatePrivateLocationRequest:
+ type: object
+ properties:
+ name:
+ type: string
+ examples:
+ - eu-west-agent
+ title: name
+ maxLength: 256
+ minLength: 1
+ description: Display name for the private location (required, 1-256 characters).
+ monitorIds:
+ type: array
+ items:
+ type: string
+ title: monitor_ids
+ description: IDs of monitors this private location should run (optional).
+ title: CreatePrivateLocationRequest
+ additionalProperties: false
+ description: CreatePrivateLocationRequest is the request to create a new private location.
+ openstatus.private_location.v1.CreatePrivateLocationResponse:
+ type: object
+ properties:
+ privateLocation:
+ title: private_location
+ description: The created private location, including its generated agent token.
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocation'
+ title: CreatePrivateLocationResponse
+ additionalProperties: false
+ description: CreatePrivateLocationResponse is the response after creating a private location.
+ openstatus.private_location.v1.DeletePrivateLocationRequest:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ minLength: 1
+ description: ID of the private location to delete (required).
+ title: DeletePrivateLocationRequest
+ additionalProperties: false
+ description: DeletePrivateLocationRequest is the request to delete a private location.
+ openstatus.private_location.v1.DeletePrivateLocationResponse:
+ type: object
+ properties:
+ success:
+ type: boolean
+ title: success
+ description: Whether the deletion was successful.
+ title: DeletePrivateLocationResponse
+ additionalProperties: false
+ description: DeletePrivateLocationResponse is the response after deleting a private location.
+ openstatus.private_location.v1.GetPrivateLocationRequest:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ minLength: 1
+ description: ID of the private location to retrieve (required).
+ title: GetPrivateLocationRequest
+ additionalProperties: false
+ description: GetPrivateLocationRequest is the request to get a private location by ID.
+ openstatus.private_location.v1.GetPrivateLocationResponse:
+ type: object
+ properties:
+ privateLocation:
+ title: private_location
+ description: The requested private location.
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocation'
+ title: GetPrivateLocationResponse
+ additionalProperties: false
+ description: GetPrivateLocationResponse is the response containing the private location.
+ openstatus.private_location.v1.ListPrivateLocationsRequest:
+ type: object
+ properties:
+ limit:
+ type:
+ - integer
+ - "null"
+ title: limit
+ maximum: 100
+ minimum: 1
+ format: int32
+ description: Maximum number of private locations to return (1-100, defaults to 50).
+ offset:
+ type:
+ - integer
+ - "null"
+ title: offset
+ minimum: 0
+ format: int32
+ description: Number of private locations to skip for pagination (defaults to 0).
+ title: ListPrivateLocationsRequest
+ additionalProperties: false
+ description: ListPrivateLocationsRequest is the request to list private locations.
+ openstatus.private_location.v1.ListPrivateLocationsResponse:
+ type: object
+ properties:
+ privateLocations:
+ type: array
+ items:
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocationSummary'
+ title: private_locations
+ description: List of private locations.
+ totalSize:
+ type: integer
+ title: total_size
+ format: int32
+ description: Total number of private locations in the workspace.
+ title: ListPrivateLocationsResponse
+ additionalProperties: false
+ description: ListPrivateLocationsResponse is the response containing private location summaries.
+ openstatus.private_location.v1.PrivateLocation:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ description: Unique identifier for the private location.
+ name:
+ type: string
+ title: name
+ description: Display name for the private location.
+ token:
+ type: string
+ title: token
+ description: |-
+ Agent credential. Generated by the server on creation and used by the
+ agent to authenticate; treat it as a secret.
+ monitorIds:
+ type: array
+ items:
+ type: string
+ title: monitor_ids
+ description: IDs of monitors this private location runs.
+ lastSeenAt:
+ type: string
+ title: last_seen_at
+ description: Last time the agent reported a result (RFC 3339), empty if it never has.
+ createdAt:
+ type: string
+ title: created_at
+ description: Timestamp when the private location was created (RFC 3339 format).
+ updatedAt:
+ type: string
+ title: updated_at
+ description: Timestamp when the private location was last updated (RFC 3339 format).
+ title: PrivateLocation
+ additionalProperties: false
+ description: PrivateLocation represents a self-hosted checker agent with full details.
+ openstatus.private_location.v1.PrivateLocationSummary:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ description: Unique identifier for the private location.
+ name:
+ type: string
+ title: name
+ description: Display name for the private location.
+ monitorCount:
+ type: integer
+ title: monitor_count
+ format: int32
+ description: Number of monitors this private location runs.
+ lastSeenAt:
+ type: string
+ title: last_seen_at
+ description: Last time the agent reported a result (RFC 3339), empty if it never has.
+ createdAt:
+ type: string
+ title: created_at
+ description: Timestamp when the private location was created (RFC 3339 format).
+ updatedAt:
+ type: string
+ title: updated_at
+ description: Timestamp when the private location was last updated (RFC 3339 format).
+ title: PrivateLocationSummary
+ additionalProperties: false
+ description: |-
+ PrivateLocationSummary represents metadata for a private location (used in
+ list responses). The agent token is intentionally omitted.
+ openstatus.private_location.v1.UpdatePrivateLocationRequest:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ minLength: 1
+ description: ID of the private location to update (required).
+ name:
+ type:
+ - string
+ - "null"
+ title: name
+ maxLength: 256
+ minLength: 1
+ description: New display name for the private location (optional).
+ monitorIds:
+ type: array
+ items:
+ type: string
+ title: monitor_ids
+ description: New list of monitor IDs. Only applied when update_monitor_ids is true.
+ updateMonitorIds:
+ type:
+ - boolean
+ - "null"
+ title: update_monitor_ids
+ description: |-
+ When true, monitor_ids replaces the current associations (an empty list
+ clears all). When false or unset, monitor_ids is ignored and existing
+ associations are preserved.
+ title: UpdatePrivateLocationRequest
+ additionalProperties: false
+ description: UpdatePrivateLocationRequest is the request to update a private location.
+ openstatus.private_location.v1.UpdatePrivateLocationResponse:
+ type: object
+ properties:
+ privateLocation:
+ title: private_location
+ description: The updated private location.
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocation'
+ title: UpdatePrivateLocationResponse
+ additionalProperties: false
+ description: UpdatePrivateLocationResponse is the response after updating a private location.
openstatus.status_page.v1.AddMonitorComponentRequest:
type: object
properties:
@@ -4381,6 +4608,10 @@ tags:
notified automatically when maintenance is created.
- name: HealthService
description: Health check endpoint for load balancer probes. No authentication required.
+ - name: PrivateLocationService
+ description: |-
+ PrivateLocationService provides CRUD operations for private locations —
+ self-hosted checker agents that run monitors from your own network.
paths:
/rpc/openstatus.health.v1.HealthService/Check:
get:
@@ -5400,6 +5631,196 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/openstatus.notification.v1.UpdateNotificationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/CreatePrivateLocation:
+ post:
+ tags:
+ - PrivateLocationService
+ summary: CreatePrivateLocation
+ description: Creates a private location. The agent token is generated by the server and returned in the response - it cannot be supplied by the caller. Use the token to configure the agent so it can pull its monitors and report results.
+ operationId: PrivateLocationService_CreatePrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.CreatePrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.CreatePrivateLocationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/DeletePrivateLocation:
+ post:
+ tags:
+ - PrivateLocationService
+ summary: DeletePrivateLocation
+ description: DeletePrivateLocation removes a private location.
+ operationId: PrivateLocationService_DeletePrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.DeletePrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.DeletePrivateLocationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/GetPrivateLocation:
+ get:
+ tags:
+ - PrivateLocationService
+ summary: GetPrivateLocation
+ description: |-
+ GetPrivateLocation retrieves a single private location by ID, including
+ its agent token.
+ operationId: PrivateLocationService_GetPrivateLocation.get
+ parameters:
+ - name: message
+ in: query
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationRequest'
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationResponse'
+ post:
+ tags:
+ - PrivateLocationService
+ summary: GetPrivateLocation
+ description: |-
+ GetPrivateLocation retrieves a single private location by ID, including
+ its agent token.
+ operationId: PrivateLocationService_GetPrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/ListPrivateLocations:
+ get:
+ tags:
+ - PrivateLocationService
+ summary: ListPrivateLocations
+ description: |-
+ ListPrivateLocations returns a paginated list of private location
+ summaries. Agent tokens are not included - use GetPrivateLocation.
+ operationId: PrivateLocationService_ListPrivateLocations.get
+ parameters:
+ - name: message
+ in: query
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsRequest'
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsResponse'
+ post:
+ tags:
+ - PrivateLocationService
+ summary: ListPrivateLocations
+ description: |-
+ ListPrivateLocations returns a paginated list of private location
+ summaries. Agent tokens are not included - use GetPrivateLocation.
+ operationId: PrivateLocationService_ListPrivateLocations
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/UpdatePrivateLocation:
+ post:
+ tags:
+ - PrivateLocationService
+ summary: UpdatePrivateLocation
+ description: UpdatePrivateLocation updates a private location.
+ operationId: PrivateLocationService_UpdatePrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.UpdatePrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.UpdatePrivateLocationResponse'
/rpc/openstatus.status_page.v1.StatusPageService/AddMonitorComponent:
post:
tags:
diff --git a/packages/analytics/src/events.ts b/packages/analytics/src/events.ts
index 220b61b9d..114a64fb8 100644
--- a/packages/analytics/src/events.ts
+++ b/packages/analytics/src/events.ts
@@ -136,6 +136,18 @@ export const Events = {
name: "notification_deleted",
channel: "notification",
},
+ CreatePrivateLocation: {
+ name: "private_location_created",
+ channel: "private_location",
+ },
+ UpdatePrivateLocation: {
+ name: "private_location_updated",
+ channel: "private_location",
+ },
+ DeletePrivateLocation: {
+ name: "private_location_deleted",
+ channel: "private_location",
+ },
AcknowledgeIncident: {
name: "incident_acknowledged",
channel: "incident",
diff --git a/packages/api/src/router/privateLocation.ts b/packages/api/src/router/privateLocation.ts
index b21a35049..0ae5f821b 100644
--- a/packages/api/src/router/privateLocation.ts
+++ b/packages/api/src/router/privateLocation.ts
@@ -15,7 +15,11 @@ export const privateLocationRouter = createTRPCRouter({
.input(ListPrivateLocationsInput.optional())
.query(async ({ ctx, input }) => {
try {
- return await listPrivateLocations({ ctx: toServiceCtx(ctx), input });
+ const { items } = await listPrivateLocations({
+ ctx: toServiceCtx(ctx),
+ input,
+ });
+ return items;
} catch (err) {
toTRPCError(err);
}
diff --git a/packages/proto/api/openstatus/private_location/v1/private_location.proto b/packages/proto/api/openstatus/private_location/v1/private_location.proto
new file mode 100644
index 000000000..cb0c63e30
--- /dev/null
+++ b/packages/proto/api/openstatus/private_location/v1/private_location.proto
@@ -0,0 +1,52 @@
+syntax = "proto3";
+
+package openstatus.private_location.v1;
+
+option go_package = "github.com/openstatushq/openstatus/packages/proto/openstatus/private_location/v1;privatelocationv1";
+
+// PrivateLocation represents a self-hosted checker agent with full details.
+message PrivateLocation {
+ // Unique identifier for the private location.
+ string id = 1;
+
+ // Display name for the private location.
+ string name = 2;
+
+ // Agent credential. Generated by the server on creation and used by the
+ // agent to authenticate; treat it as a secret.
+ string token = 3;
+
+ // IDs of monitors this private location runs.
+ repeated string monitor_ids = 4;
+
+ // Last time the agent reported a result (RFC 3339), empty if it never has.
+ string last_seen_at = 5;
+
+ // Timestamp when the private location was created (RFC 3339 format).
+ string created_at = 6;
+
+ // Timestamp when the private location was last updated (RFC 3339 format).
+ string updated_at = 7;
+}
+
+// PrivateLocationSummary represents metadata for a private location (used in
+// list responses). The agent token is intentionally omitted.
+message PrivateLocationSummary {
+ // Unique identifier for the private location.
+ string id = 1;
+
+ // Display name for the private location.
+ string name = 2;
+
+ // Number of monitors this private location runs.
+ int32 monitor_count = 3;
+
+ // Last time the agent reported a result (RFC 3339), empty if it never has.
+ string last_seen_at = 4;
+
+ // Timestamp when the private location was created (RFC 3339 format).
+ string created_at = 5;
+
+ // Timestamp when the private location was last updated (RFC 3339 format).
+ string updated_at = 6;
+}
diff --git a/packages/proto/api/openstatus/private_location/v1/service.proto b/packages/proto/api/openstatus/private_location/v1/service.proto
new file mode 100644
index 000000000..6f80c5783
--- /dev/null
+++ b/packages/proto/api/openstatus/private_location/v1/service.proto
@@ -0,0 +1,131 @@
+syntax = "proto3";
+
+package openstatus.private_location.v1;
+
+import "buf/validate/validate.proto";
+import "gnostic/openapi/v3/annotations.proto";
+import "openstatus/private_location/v1/private_location.proto";
+
+option go_package = "github.com/openstatushq/openstatus/packages/proto/openstatus/private_location/v1;privatelocationv1";
+
+// PrivateLocationService provides CRUD operations for private locations —
+// self-hosted checker agents that run monitors from your own network.
+service PrivateLocationService {
+ // CreatePrivateLocation creates a new private location and returns its
+ // generated agent token.
+ rpc CreatePrivateLocation(CreatePrivateLocationRequest) returns (CreatePrivateLocationResponse) {
+ option (gnostic.openapi.v3.operation) = {
+ description: "Creates a private location. The agent token is generated by the server and returned in the response - it cannot be supplied by the caller. Use the token to configure the agent so it can pull its monitors and report results."
+ };
+ }
+
+ // GetPrivateLocation retrieves a single private location by ID, including
+ // its agent token.
+ rpc GetPrivateLocation(GetPrivateLocationRequest) returns (GetPrivateLocationResponse) {
+ option idempotency_level = NO_SIDE_EFFECTS;
+ }
+
+ // ListPrivateLocations returns a paginated list of private location
+ // summaries. Agent tokens are not included - use GetPrivateLocation.
+ rpc ListPrivateLocations(ListPrivateLocationsRequest) returns (ListPrivateLocationsResponse) {
+ option idempotency_level = NO_SIDE_EFFECTS;
+ }
+
+ // UpdatePrivateLocation updates a private location.
+ rpc UpdatePrivateLocation(UpdatePrivateLocationRequest) returns (UpdatePrivateLocationResponse);
+
+ // DeletePrivateLocation removes a private location.
+ rpc DeletePrivateLocation(DeletePrivateLocationRequest) returns (DeletePrivateLocationResponse);
+}
+
+// CreatePrivateLocationRequest is the request to create a new private location.
+message CreatePrivateLocationRequest {
+ // Display name for the private location (required, 1-256 characters).
+ string name = 1 [
+ (buf.validate.field).string = {
+ min_len: 1
+ max_len: 256
+ },
+ (gnostic.openapi.v3.property) = {example: {yaml: "eu-west-agent"}}
+ ];
+
+ // IDs of monitors this private location should run (optional).
+ repeated string monitor_ids = 2;
+}
+
+// CreatePrivateLocationResponse is the response after creating a private location.
+message CreatePrivateLocationResponse {
+ // The created private location, including its generated agent token.
+ PrivateLocation private_location = 1;
+}
+
+// GetPrivateLocationRequest is the request to get a private location by ID.
+message GetPrivateLocationRequest {
+ // ID of the private location to retrieve (required).
+ string id = 1 [(buf.validate.field).string.min_len = 1];
+}
+
+// GetPrivateLocationResponse is the response containing the private location.
+message GetPrivateLocationResponse {
+ // The requested private location.
+ PrivateLocation private_location = 1;
+}
+
+// ListPrivateLocationsRequest is the request to list private locations.
+message ListPrivateLocationsRequest {
+ // Maximum number of private locations to return (1-100, defaults to 50).
+ optional int32 limit = 1 [(buf.validate.field).int32 = {
+ gte: 1
+ lte: 100
+ }];
+
+ // Number of private locations to skip for pagination (defaults to 0).
+ optional int32 offset = 2 [(buf.validate.field).int32.gte = 0];
+}
+
+// ListPrivateLocationsResponse is the response containing private location summaries.
+message ListPrivateLocationsResponse {
+ // List of private locations.
+ repeated PrivateLocationSummary private_locations = 1;
+
+ // Total number of private locations in the workspace.
+ int32 total_size = 2;
+}
+
+// UpdatePrivateLocationRequest is the request to update a private location.
+message UpdatePrivateLocationRequest {
+ // ID of the private location to update (required).
+ string id = 1 [(buf.validate.field).string.min_len = 1];
+
+ // New display name for the private location (optional).
+ optional string name = 2 [(buf.validate.field).string = {
+ min_len: 1
+ max_len: 256
+ }];
+
+ // New list of monitor IDs. Only applied when update_monitor_ids is true.
+ repeated string monitor_ids = 3;
+
+ // When true, monitor_ids replaces the current associations (an empty list
+ // clears all). When false or unset, monitor_ids is ignored and existing
+ // associations are preserved.
+ optional bool update_monitor_ids = 4;
+}
+
+// UpdatePrivateLocationResponse is the response after updating a private location.
+message UpdatePrivateLocationResponse {
+ // The updated private location.
+ PrivateLocation private_location = 1;
+}
+
+// DeletePrivateLocationRequest is the request to delete a private location.
+message DeletePrivateLocationRequest {
+ // ID of the private location to delete (required).
+ string id = 1 [(buf.validate.field).string.min_len = 1];
+}
+
+// DeletePrivateLocationResponse is the response after deleting a private location.
+message DeletePrivateLocationResponse {
+ // Whether the deletion was successful.
+ bool success = 1;
+}
diff --git a/packages/proto/gen/openapi.yaml b/packages/proto/gen/openapi.yaml
index 9ad73d881..324d1369a 100644
--- a/packages/proto/gen/openapi.yaml
+++ b/packages/proto/gen/openapi.yaml
@@ -2325,6 +2325,233 @@ components:
title: WhatsappData
additionalProperties: false
description: WhatsappData contains configuration for WhatsApp notifications.
+ openstatus.private_location.v1.CreatePrivateLocationRequest:
+ type: object
+ properties:
+ name:
+ type: string
+ examples:
+ - eu-west-agent
+ title: name
+ maxLength: 256
+ minLength: 1
+ description: Display name for the private location (required, 1-256 characters).
+ monitorIds:
+ type: array
+ items:
+ type: string
+ title: monitor_ids
+ description: IDs of monitors this private location should run (optional).
+ title: CreatePrivateLocationRequest
+ additionalProperties: false
+ description: CreatePrivateLocationRequest is the request to create a new private location.
+ openstatus.private_location.v1.CreatePrivateLocationResponse:
+ type: object
+ properties:
+ privateLocation:
+ title: private_location
+ description: The created private location, including its generated agent token.
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocation'
+ title: CreatePrivateLocationResponse
+ additionalProperties: false
+ description: CreatePrivateLocationResponse is the response after creating a private location.
+ openstatus.private_location.v1.DeletePrivateLocationRequest:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ minLength: 1
+ description: ID of the private location to delete (required).
+ title: DeletePrivateLocationRequest
+ additionalProperties: false
+ description: DeletePrivateLocationRequest is the request to delete a private location.
+ openstatus.private_location.v1.DeletePrivateLocationResponse:
+ type: object
+ properties:
+ success:
+ type: boolean
+ title: success
+ description: Whether the deletion was successful.
+ title: DeletePrivateLocationResponse
+ additionalProperties: false
+ description: DeletePrivateLocationResponse is the response after deleting a private location.
+ openstatus.private_location.v1.GetPrivateLocationRequest:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ minLength: 1
+ description: ID of the private location to retrieve (required).
+ title: GetPrivateLocationRequest
+ additionalProperties: false
+ description: GetPrivateLocationRequest is the request to get a private location by ID.
+ openstatus.private_location.v1.GetPrivateLocationResponse:
+ type: object
+ properties:
+ privateLocation:
+ title: private_location
+ description: The requested private location.
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocation'
+ title: GetPrivateLocationResponse
+ additionalProperties: false
+ description: GetPrivateLocationResponse is the response containing the private location.
+ openstatus.private_location.v1.ListPrivateLocationsRequest:
+ type: object
+ properties:
+ limit:
+ type:
+ - integer
+ - "null"
+ title: limit
+ maximum: 100
+ minimum: 1
+ format: int32
+ description: Maximum number of private locations to return (1-100, defaults to 50).
+ offset:
+ type:
+ - integer
+ - "null"
+ title: offset
+ minimum: 0
+ format: int32
+ description: Number of private locations to skip for pagination (defaults to 0).
+ title: ListPrivateLocationsRequest
+ additionalProperties: false
+ description: ListPrivateLocationsRequest is the request to list private locations.
+ openstatus.private_location.v1.ListPrivateLocationsResponse:
+ type: object
+ properties:
+ privateLocations:
+ type: array
+ items:
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocationSummary'
+ title: private_locations
+ description: List of private locations.
+ totalSize:
+ type: integer
+ title: total_size
+ format: int32
+ description: Total number of private locations in the workspace.
+ title: ListPrivateLocationsResponse
+ additionalProperties: false
+ description: ListPrivateLocationsResponse is the response containing private location summaries.
+ openstatus.private_location.v1.PrivateLocation:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ description: Unique identifier for the private location.
+ name:
+ type: string
+ title: name
+ description: Display name for the private location.
+ token:
+ type: string
+ title: token
+ description: |-
+ Agent credential. Generated by the server on creation and used by the
+ agent to authenticate; treat it as a secret.
+ monitorIds:
+ type: array
+ items:
+ type: string
+ title: monitor_ids
+ description: IDs of monitors this private location runs.
+ lastSeenAt:
+ type: string
+ title: last_seen_at
+ description: Last time the agent reported a result (RFC 3339), empty if it never has.
+ createdAt:
+ type: string
+ title: created_at
+ description: Timestamp when the private location was created (RFC 3339 format).
+ updatedAt:
+ type: string
+ title: updated_at
+ description: Timestamp when the private location was last updated (RFC 3339 format).
+ title: PrivateLocation
+ additionalProperties: false
+ description: PrivateLocation represents a self-hosted checker agent with full details.
+ openstatus.private_location.v1.PrivateLocationSummary:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ description: Unique identifier for the private location.
+ name:
+ type: string
+ title: name
+ description: Display name for the private location.
+ monitorCount:
+ type: integer
+ title: monitor_count
+ format: int32
+ description: Number of monitors this private location runs.
+ lastSeenAt:
+ type: string
+ title: last_seen_at
+ description: Last time the agent reported a result (RFC 3339), empty if it never has.
+ createdAt:
+ type: string
+ title: created_at
+ description: Timestamp when the private location was created (RFC 3339 format).
+ updatedAt:
+ type: string
+ title: updated_at
+ description: Timestamp when the private location was last updated (RFC 3339 format).
+ title: PrivateLocationSummary
+ additionalProperties: false
+ description: |-
+ PrivateLocationSummary represents metadata for a private location (used in
+ list responses). The agent token is intentionally omitted.
+ openstatus.private_location.v1.UpdatePrivateLocationRequest:
+ type: object
+ properties:
+ id:
+ type: string
+ title: id
+ minLength: 1
+ description: ID of the private location to update (required).
+ name:
+ type:
+ - string
+ - "null"
+ title: name
+ maxLength: 256
+ minLength: 1
+ description: New display name for the private location (optional).
+ monitorIds:
+ type: array
+ items:
+ type: string
+ title: monitor_ids
+ description: New list of monitor IDs. Only applied when update_monitor_ids is true.
+ updateMonitorIds:
+ type:
+ - boolean
+ - "null"
+ title: update_monitor_ids
+ description: |-
+ When true, monitor_ids replaces the current associations (an empty list
+ clears all). When false or unset, monitor_ids is ignored and existing
+ associations are preserved.
+ title: UpdatePrivateLocationRequest
+ additionalProperties: false
+ description: UpdatePrivateLocationRequest is the request to update a private location.
+ openstatus.private_location.v1.UpdatePrivateLocationResponse:
+ type: object
+ properties:
+ privateLocation:
+ title: private_location
+ description: The updated private location.
+ $ref: '#/components/schemas/openstatus.private_location.v1.PrivateLocation'
+ title: UpdatePrivateLocationResponse
+ additionalProperties: false
+ description: UpdatePrivateLocationResponse is the response after updating a private location.
openstatus.status_page.v1.AddMonitorComponentRequest:
type: object
properties:
@@ -4381,6 +4608,10 @@ tags:
notified automatically when maintenance is created.
- name: HealthService
description: Health check endpoint for load balancer probes. No authentication required.
+ - name: PrivateLocationService
+ description: |-
+ PrivateLocationService provides CRUD operations for private locations —
+ self-hosted checker agents that run monitors from your own network.
paths:
/rpc/openstatus.health.v1.HealthService/Check:
get:
@@ -5400,6 +5631,196 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/openstatus.notification.v1.UpdateNotificationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/CreatePrivateLocation:
+ post:
+ tags:
+ - PrivateLocationService
+ summary: CreatePrivateLocation
+ description: Creates a private location. The agent token is generated by the server and returned in the response - it cannot be supplied by the caller. Use the token to configure the agent so it can pull its monitors and report results.
+ operationId: PrivateLocationService_CreatePrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.CreatePrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.CreatePrivateLocationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/DeletePrivateLocation:
+ post:
+ tags:
+ - PrivateLocationService
+ summary: DeletePrivateLocation
+ description: DeletePrivateLocation removes a private location.
+ operationId: PrivateLocationService_DeletePrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.DeletePrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.DeletePrivateLocationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/GetPrivateLocation:
+ get:
+ tags:
+ - PrivateLocationService
+ summary: GetPrivateLocation
+ description: |-
+ GetPrivateLocation retrieves a single private location by ID, including
+ its agent token.
+ operationId: PrivateLocationService_GetPrivateLocation.get
+ parameters:
+ - name: message
+ in: query
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationRequest'
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationResponse'
+ post:
+ tags:
+ - PrivateLocationService
+ summary: GetPrivateLocation
+ description: |-
+ GetPrivateLocation retrieves a single private location by ID, including
+ its agent token.
+ operationId: PrivateLocationService_GetPrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.GetPrivateLocationResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/ListPrivateLocations:
+ get:
+ tags:
+ - PrivateLocationService
+ summary: ListPrivateLocations
+ description: |-
+ ListPrivateLocations returns a paginated list of private location
+ summaries. Agent tokens are not included - use GetPrivateLocation.
+ operationId: PrivateLocationService_ListPrivateLocations.get
+ parameters:
+ - name: message
+ in: query
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsRequest'
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsResponse'
+ post:
+ tags:
+ - PrivateLocationService
+ summary: ListPrivateLocations
+ description: |-
+ ListPrivateLocations returns a paginated list of private location
+ summaries. Agent tokens are not included - use GetPrivateLocation.
+ operationId: PrivateLocationService_ListPrivateLocations
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.ListPrivateLocationsResponse'
+ /rpc/openstatus.private_location.v1.PrivateLocationService/UpdatePrivateLocation:
+ post:
+ tags:
+ - PrivateLocationService
+ summary: UpdatePrivateLocation
+ description: UpdatePrivateLocation updates a private location.
+ operationId: PrivateLocationService_UpdatePrivateLocation
+ requestBody:
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.UpdatePrivateLocationRequest'
+ required: true
+ responses:
+ default:
+ description: Error
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/connect.error'
+ "200":
+ description: Success
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/openstatus.private_location.v1.UpdatePrivateLocationResponse'
/rpc/openstatus.status_page.v1.StatusPageService/AddMonitorComponent:
post:
tags:
diff --git a/packages/proto/gen/ts/openstatus/private_location/v1/index.ts b/packages/proto/gen/ts/openstatus/private_location/v1/index.ts
new file mode 100644
index 000000000..60fd4d266
--- /dev/null
+++ b/packages/proto/gen/ts/openstatus/private_location/v1/index.ts
@@ -0,0 +1,3 @@
+// Private location service exports
+export * from "./private_location_pb.js";
+export * from "./service_pb.js";
diff --git a/packages/proto/gen/ts/openstatus/private_location/v1/private_location_pb.ts b/packages/proto/gen/ts/openstatus/private_location/v1/private_location_pb.ts
new file mode 100644
index 000000000..1618cef8f
--- /dev/null
+++ b/packages/proto/gen/ts/openstatus/private_location/v1/private_location_pb.ts
@@ -0,0 +1,135 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=ts,import_extension=.ts"
+// @generated from file openstatus/private_location/v1/private_location.proto (package openstatus.private_location.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc } from "@bufbuild/protobuf/codegenv2";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file openstatus/private_location/v1/private_location.proto.
+ */
+export const file_openstatus_private_location_v1_private_location: GenFile = /*@__PURE__*/
+ fileDesc("CjVvcGVuc3RhdHVzL3ByaXZhdGVfbG9jYXRpb24vdjEvcHJpdmF0ZV9sb2NhdGlvbi5wcm90bxIeb3BlbnN0YXR1cy5wcml2YXRlX2xvY2F0aW9uLnYxIo0BCg9Qcml2YXRlTG9jYXRpb24SCgoCaWQYASABKAkSDAoEbmFtZRgCIAEoCRINCgV0b2tlbhgDIAEoCRITCgttb25pdG9yX2lkcxgEIAMoCRIUCgxsYXN0X3NlZW5fYXQYBSABKAkSEgoKY3JlYXRlZF9hdBgGIAEoCRISCgp1cGRhdGVkX2F0GAcgASgJIocBChZQcml2YXRlTG9jYXRpb25TdW1tYXJ5EgoKAmlkGAEgASgJEgwKBG5hbWUYAiABKAkSFQoNbW9uaXRvcl9jb3VudBgDIAEoBRIUCgxsYXN0X3NlZW5fYXQYBCABKAkSEgoKY3JlYXRlZF9hdBgFIAEoCRISCgp1cGRhdGVkX2F0GAYgASgJQmRaYmdpdGh1Yi5jb20vb3BlbnN0YXR1c2hxL29wZW5zdGF0dXMvcGFja2FnZXMvcHJvdG8vb3BlbnN0YXR1cy9wcml2YXRlX2xvY2F0aW9uL3YxO3ByaXZhdGVsb2NhdGlvbnYxYgZwcm90bzM");
+
+/**
+ * PrivateLocation represents a self-hosted checker agent with full details.
+ *
+ * @generated from message openstatus.private_location.v1.PrivateLocation
+ */
+export type PrivateLocation = Message<"openstatus.private_location.v1.PrivateLocation"> & {
+ /**
+ * Unique identifier for the private location.
+ *
+ * @generated from field: string id = 1;
+ */
+ id: string;
+
+ /**
+ * Display name for the private location.
+ *
+ * @generated from field: string name = 2;
+ */
+ name: string;
+
+ /**
+ * Agent credential. Generated by the server on creation and used by the
+ * agent to authenticate; treat it as a secret.
+ *
+ * @generated from field: string token = 3;
+ */
+ token: string;
+
+ /**
+ * IDs of monitors this private location runs.
+ *
+ * @generated from field: repeated string monitor_ids = 4;
+ */
+ monitorIds: string[];
+
+ /**
+ * Last time the agent reported a result (RFC 3339), empty if it never has.
+ *
+ * @generated from field: string last_seen_at = 5;
+ */
+ lastSeenAt: string;
+
+ /**
+ * Timestamp when the private location was created (RFC 3339 format).
+ *
+ * @generated from field: string created_at = 6;
+ */
+ createdAt: string;
+
+ /**
+ * Timestamp when the private location was last updated (RFC 3339 format).
+ *
+ * @generated from field: string updated_at = 7;
+ */
+ updatedAt: string;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.PrivateLocation.
+ * Use `create(PrivateLocationSchema)` to create a new message.
+ */
+export const PrivateLocationSchema: GenMessage<PrivateLocation> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_private_location, 0);
+
+/**
+ * PrivateLocationSummary represents metadata for a private location (used in
+ * list responses). The agent token is intentionally omitted.
+ *
+ * @generated from message openstatus.private_location.v1.PrivateLocationSummary
+ */
+export type PrivateLocationSummary = Message<"openstatus.private_location.v1.PrivateLocationSummary"> & {
+ /**
+ * Unique identifier for the private location.
+ *
+ * @generated from field: string id = 1;
+ */
+ id: string;
+
+ /**
+ * Display name for the private location.
+ *
+ * @generated from field: string name = 2;
+ */
+ name: string;
+
+ /**
+ * Number of monitors this private location runs.
+ *
+ * @generated from field: int32 monitor_count = 3;
+ */
+ monitorCount: number;
+
+ /**
+ * Last time the agent reported a result (RFC 3339), empty if it never has.
+ *
+ * @generated from field: string last_seen_at = 4;
+ */
+ lastSeenAt: string;
+
+ /**
+ * Timestamp when the private location was created (RFC 3339 format).
+ *
+ * @generated from field: string created_at = 5;
+ */
+ createdAt: string;
+
+ /**
+ * Timestamp when the private location was last updated (RFC 3339 format).
+ *
+ * @generated from field: string updated_at = 6;
+ */
+ updatedAt: string;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.PrivateLocationSummary.
+ * Use `create(PrivateLocationSummarySchema)` to create a new message.
+ */
+export const PrivateLocationSummarySchema: GenMessage<PrivateLocationSummary> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_private_location, 1);
+
diff --git a/packages/proto/gen/ts/openstatus/private_location/v1/service_pb.ts b/packages/proto/gen/ts/openstatus/private_location/v1/service_pb.ts
new file mode 100644
index 000000000..a8d4c7395
--- /dev/null
+++ b/packages/proto/gen/ts/openstatus/private_location/v1/service_pb.ts
@@ -0,0 +1,335 @@
+// @generated by protoc-gen-es v2.12.0 with parameter "target=ts,import_extension=.ts"
+// @generated from file openstatus/private_location/v1/service.proto (package openstatus.private_location.v1, syntax proto3)
+/* eslint-disable */
+
+import type { GenFile, GenMessage, GenService } from "@bufbuild/protobuf/codegenv2";
+import { fileDesc, messageDesc, serviceDesc } from "@bufbuild/protobuf/codegenv2";
+import { file_buf_validate_validate } from "../../../buf/validate/validate_pb.ts";
+import { file_gnostic_openapi_v3_annotations } from "../../../gnostic/openapi/v3/annotations_pb.ts";
+import type { PrivateLocation, PrivateLocationSummary } from "./private_location_pb.ts";
+import { file_openstatus_private_location_v1_private_location } from "./private_location_pb.ts";
+import type { Message } from "@bufbuild/protobuf";
+
+/**
+ * Describes the file openstatus/private_location/v1/service.proto.
+ */
+export const file_openstatus_private_location_v1_service: GenFile = /*@__PURE__*/
+ fileDesc("CixvcGVuc3RhdHVzL3ByaXZhdGVfbG9jYXRpb24vdjEvc2VydmljZS5wcm90bxIeb3BlbnN0YXR1cy5wcml2YXRlX2xvY2F0aW9uLnYxImEKHENyZWF0ZVByaXZhdGVMb2NhdGlvblJlcXVlc3QSLAoEbmFtZRgBIAEoCUIeukcROg8SDWV1LXdlc3QtYWdlbnS6SAdyBRABGIACEhMKC21vbml0b3JfaWRzGAIgAygJImoKHUNyZWF0ZVByaXZhdGVMb2NhdGlvblJlc3BvbnNlEkkKEHByaXZhdGVfbG9jYXRpb24YASABKAsyLy5vcGVuc3RhdHVzLnByaXZhdGVfbG9jYXRpb24udjEuUHJpdmF0ZUxvY2F0aW9uIjAKGUdldFByaXZhdGVMb2NhdGlvblJlcXVlc3QSEwoCaWQYASABKAlCB7pIBHICEAEiZwoaR2V0UHJpdmF0ZUxvY2F0aW9uUmVzcG9uc2USSQoQcHJpdmF0ZV9sb2NhdGlvbhgBIAEoCzIvLm9wZW5zdGF0dXMucHJpdmF0ZV9sb2NhdGlvbi52MS5Qcml2YXRlTG9jYXRpb24ibwobTGlzdFByaXZhdGVMb2NhdGlvbnNSZXF1ZXN0Eh0KBWxpbWl0GAEgASgFQgm6SAYaBBhkKAFIAIgBARIcCgZvZmZzZXQYAiABKAVCB7pIBBoCKABIAYgBAUIICgZfbGltaXRCCQoHX29mZnNldCKFAQocTGlzdFByaXZhdGVMb2NhdGlvbnNSZXNwb25zZRJRChFwcml2YXRlX2xvY2F0aW9ucxgBIAMoCzI2Lm9wZW5zdGF0dXMucHJpdmF0ZV9sb2NhdGlvbi52MS5Qcml2YXRlTG9jYXRpb25TdW1tYXJ5EhIKCnRvdGFsX3NpemUYAiABKAUiqAEKHFVwZGF0ZVByaXZhdGVMb2NhdGlvblJlcXVlc3QSEwoCaWQYASABKAlCB7pIBHICEAESHQoEbmFtZRgCIAEoCUIKukgHcgUQARiAAkgAiAEBEhMKC21vbml0b3JfaWRzGAMgAygJEh8KEnVwZGF0ZV9tb25pdG9yX2lkcxgEIAEoCEgBiAEBQgcKBV9uYW1lQhUKE191cGRhdGVfbW9uaXRvcl9pZHMiagodVXBkYXRlUHJpdmF0ZUxvY2F0aW9uUmVzcG9uc2USSQoQcHJpdmF0ZV9sb2NhdGlvbhgBIAEoCzIvLm9wZW5zdGF0dXMucHJpdmF0ZV9sb2NhdGlvbi52MS5Qcml2YXRlTG9jYXRpb24iMwocRGVsZXRlUHJpdmF0ZUxvY2F0aW9uUmVxdWVzdBITCgJpZBgBIAEoCUIHukgEcgIQASIwCh1EZWxldGVQcml2YXRlTG9jYXRpb25SZXNwb25zZRIPCgdzdWNjZXNzGAEgASgIMvIHChZQcml2YXRlTG9jYXRpb25TZXJ2aWNlEv0CChVDcmVhdGVQcml2YXRlTG9jYXRpb24SPC5vcGVuc3RhdHVzLnByaXZhdGVfbG9jYXRpb24udjEuQ3JlYXRlUHJpdmF0ZUxvY2F0aW9uUmVxdWVzdBo9Lm9wZW5zdGF0dXMucHJpdmF0ZV9sb2NhdGlvbi52MS5DcmVhdGVQcml2YXRlTG9jYXRpb25SZXNwb25zZSLmAbpH4gEa3wFDcmVhdGVzIGEgcHJpdmF0ZSBsb2NhdGlvbi4gVGhlIGFnZW50IHRva2VuIGlzIGdlbmVyYXRlZCBieSB0aGUgc2VydmVyIGFuZCByZXR1cm5lZCBpbiB0aGUgcmVzcG9uc2UgLSBpdCBjYW5ub3QgYmUgc3VwcGxpZWQgYnkgdGhlIGNhbGxlci4gVXNlIHRoZSB0b2tlbiB0byBjb25maWd1cmUgdGhlIGFnZW50IHNvIGl0IGNhbiBwdWxsIGl0cyBtb25pdG9ycyBhbmQgcmVwb3J0IHJlc3VsdHMuEpABChJHZXRQcml2YXRlTG9jYXRpb24SOS5vcGVuc3RhdHVzLnByaXZhdGVfbG9jYXRpb24udjEuR2V0UHJpdmF0ZUxvY2F0aW9uUmVxdWVzdBo6Lm9wZW5zdGF0dXMucHJpdmF0ZV9sb2NhdGlvbi52MS5HZXRQcml2YXRlTG9jYXRpb25SZXNwb25zZSIDkAIBEpYBChRMaXN0UHJpdmF0ZUxvY2F0aW9ucxI7Lm9wZW5zdGF0dXMucHJpdmF0ZV9sb2NhdGlvbi52MS5MaXN0UHJpdmF0ZUxvY2F0aW9uc1JlcXVlc3QaPC5vcGVuc3RhdHVzLnByaXZhdGVfbG9jYXRpb24udjEuTGlzdFByaXZhdGVMb2NhdGlvbnNSZXNwb25zZSIDkAIBEpQBChVVcGRhdGVQcml2YXRlTG9jYXRpb24SPC5vcGVuc3RhdHVzLnByaXZhdGVfbG9jYXRpb24udjEuVXBkYXRlUHJpdmF0ZUxvY2F0aW9uUmVxdWVzdBo9Lm9wZW5zdGF0dXMucHJpdmF0ZV9sb2NhdGlvbi52MS5VcGRhdGVQcml2YXRlTG9jYXRpb25SZXNwb25zZRKUAQoVRGVsZXRlUHJpdmF0ZUxvY2F0aW9uEjwub3BlbnN0YXR1cy5wcml2YXRlX2xvY2F0aW9uLnYxLkRlbGV0ZVByaXZhdGVMb2NhdGlvblJlcXVlc3QaPS5vcGVuc3RhdHVzLnByaXZhdGVfbG9jYXRpb24udjEuRGVsZXRlUHJpdmF0ZUxvY2F0aW9uUmVzcG9uc2VCZFpiZ2l0aHViLmNvbS9vcGVuc3RhdHVzaHEvb3BlbnN0YXR1cy9wYWNrYWdlcy9wcm90by9vcGVuc3RhdHVzL3ByaXZhdGVfbG9jYXRpb24vdjE7cHJpdmF0ZWxvY2F0aW9udjFiBnByb3RvMw", [file_buf_validate_validate, file_gnostic_openapi_v3_annotations, file_openstatus_private_location_v1_private_location]);
+
+/**
+ * CreatePrivateLocationRequest is the request to create a new private location.
+ *
+ * @generated from message openstatus.private_location.v1.CreatePrivateLocationRequest
+ */
+export type CreatePrivateLocationRequest = Message<"openstatus.private_location.v1.CreatePrivateLocationRequest"> & {
+ /**
+ * Display name for the private location (required, 1-256 characters).
+ *
+ * @generated from field: string name = 1;
+ */
+ name: string;
+
+ /**
+ * IDs of monitors this private location should run (optional).
+ *
+ * @generated from field: repeated string monitor_ids = 2;
+ */
+ monitorIds: string[];
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.CreatePrivateLocationRequest.
+ * Use `create(CreatePrivateLocationRequestSchema)` to create a new message.
+ */
+export const CreatePrivateLocationRequestSchema: GenMessage<CreatePrivateLocationRequest> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 0);
+
+/**
+ * CreatePrivateLocationResponse is the response after creating a private location.
+ *
+ * @generated from message openstatus.private_location.v1.CreatePrivateLocationResponse
+ */
+export type CreatePrivateLocationResponse = Message<"openstatus.private_location.v1.CreatePrivateLocationResponse"> & {
+ /**
+ * The created private location, including its generated agent token.
+ *
+ * @generated from field: openstatus.private_location.v1.PrivateLocation private_location = 1;
+ */
+ privateLocation?: PrivateLocation | undefined;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.CreatePrivateLocationResponse.
+ * Use `create(CreatePrivateLocationResponseSchema)` to create a new message.
+ */
+export const CreatePrivateLocationResponseSchema: GenMessage<CreatePrivateLocationResponse> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 1);
+
+/**
+ * GetPrivateLocationRequest is the request to get a private location by ID.
+ *
+ * @generated from message openstatus.private_location.v1.GetPrivateLocationRequest
+ */
+export type GetPrivateLocationRequest = Message<"openstatus.private_location.v1.GetPrivateLocationRequest"> & {
+ /**
+ * ID of the private location to retrieve (required).
+ *
+ * @generated from field: string id = 1;
+ */
+ id: string;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.GetPrivateLocationRequest.
+ * Use `create(GetPrivateLocationRequestSchema)` to create a new message.
+ */
+export const GetPrivateLocationRequestSchema: GenMessage<GetPrivateLocationRequest> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 2);
+
+/**
+ * GetPrivateLocationResponse is the response containing the private location.
+ *
+ * @generated from message openstatus.private_location.v1.GetPrivateLocationResponse
+ */
+export type GetPrivateLocationResponse = Message<"openstatus.private_location.v1.GetPrivateLocationResponse"> & {
+ /**
+ * The requested private location.
+ *
+ * @generated from field: openstatus.private_location.v1.PrivateLocation private_location = 1;
+ */
+ privateLocation?: PrivateLocation | undefined;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.GetPrivateLocationResponse.
+ * Use `create(GetPrivateLocationResponseSchema)` to create a new message.
+ */
+export const GetPrivateLocationResponseSchema: GenMessage<GetPrivateLocationResponse> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 3);
+
+/**
+ * ListPrivateLocationsRequest is the request to list private locations.
+ *
+ * @generated from message openstatus.private_location.v1.ListPrivateLocationsRequest
+ */
+export type ListPrivateLocationsRequest = Message<"openstatus.private_location.v1.ListPrivateLocationsRequest"> & {
+ /**
+ * Maximum number of private locations to return (1-100, defaults to 50).
+ *
+ * @generated from field: optional int32 limit = 1;
+ */
+ limit?: number | undefined;
+
+ /**
+ * Number of private locations to skip for pagination (defaults to 0).
+ *
+ * @generated from field: optional int32 offset = 2;
+ */
+ offset?: number | undefined;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.ListPrivateLocationsRequest.
+ * Use `create(ListPrivateLocationsRequestSchema)` to create a new message.
+ */
+export const ListPrivateLocationsRequestSchema: GenMessage<ListPrivateLocationsRequest> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 4);
+
+/**
+ * ListPrivateLocationsResponse is the response containing private location summaries.
+ *
+ * @generated from message openstatus.private_location.v1.ListPrivateLocationsResponse
+ */
+export type ListPrivateLocationsResponse = Message<"openstatus.private_location.v1.ListPrivateLocationsResponse"> & {
+ /**
+ * List of private locations.
+ *
+ * @generated from field: repeated openstatus.private_location.v1.PrivateLocationSummary private_locations = 1;
+ */
+ privateLocations: PrivateLocationSummary[];
+
+ /**
+ * Total number of private locations in the workspace.
+ *
+ * @generated from field: int32 total_size = 2;
+ */
+ totalSize: number;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.ListPrivateLocationsResponse.
+ * Use `create(ListPrivateLocationsResponseSchema)` to create a new message.
+ */
+export const ListPrivateLocationsResponseSchema: GenMessage<ListPrivateLocationsResponse> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 5);
+
+/**
+ * UpdatePrivateLocationRequest is the request to update a private location.
+ *
+ * @generated from message openstatus.private_location.v1.UpdatePrivateLocationRequest
+ */
+export type UpdatePrivateLocationRequest = Message<"openstatus.private_location.v1.UpdatePrivateLocationRequest"> & {
+ /**
+ * ID of the private location to update (required).
+ *
+ * @generated from field: string id = 1;
+ */
+ id: string;
+
+ /**
+ * New display name for the private location (optional).
+ *
+ * @generated from field: optional string name = 2;
+ */
+ name?: string | undefined;
+
+ /**
+ * New list of monitor IDs. Only applied when update_monitor_ids is true.
+ *
+ * @generated from field: repeated string monitor_ids = 3;
+ */
+ monitorIds: string[];
+
+ /**
+ * When true, monitor_ids replaces the current associations (an empty list
+ * clears all). When false or unset, monitor_ids is ignored and existing
+ * associations are preserved.
+ *
+ * @generated from field: optional bool update_monitor_ids = 4;
+ */
+ updateMonitorIds?: boolean | undefined;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.UpdatePrivateLocationRequest.
+ * Use `create(UpdatePrivateLocationRequestSchema)` to create a new message.
+ */
+export const UpdatePrivateLocationRequestSchema: GenMessage<UpdatePrivateLocationRequest> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 6);
+
+/**
+ * UpdatePrivateLocationResponse is the response after updating a private location.
+ *
+ * @generated from message openstatus.private_location.v1.UpdatePrivateLocationResponse
+ */
+export type UpdatePrivateLocationResponse = Message<"openstatus.private_location.v1.UpdatePrivateLocationResponse"> & {
+ /**
+ * The updated private location.
+ *
+ * @generated from field: openstatus.private_location.v1.PrivateLocation private_location = 1;
+ */
+ privateLocation?: PrivateLocation | undefined;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.UpdatePrivateLocationResponse.
+ * Use `create(UpdatePrivateLocationResponseSchema)` to create a new message.
+ */
+export const UpdatePrivateLocationResponseSchema: GenMessage<UpdatePrivateLocationResponse> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 7);
+
+/**
+ * DeletePrivateLocationRequest is the request to delete a private location.
+ *
+ * @generated from message openstatus.private_location.v1.DeletePrivateLocationRequest
+ */
+export type DeletePrivateLocationRequest = Message<"openstatus.private_location.v1.DeletePrivateLocationRequest"> & {
+ /**
+ * ID of the private location to delete (required).
+ *
+ * @generated from field: string id = 1;
+ */
+ id: string;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.DeletePrivateLocationRequest.
+ * Use `create(DeletePrivateLocationRequestSchema)` to create a new message.
+ */
+export const DeletePrivateLocationRequestSchema: GenMessage<DeletePrivateLocationRequest> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 8);
+
+/**
+ * DeletePrivateLocationResponse is the response after deleting a private location.
+ *
+ * @generated from message openstatus.private_location.v1.DeletePrivateLocationResponse
+ */
+export type DeletePrivateLocationResponse = Message<"openstatus.private_location.v1.DeletePrivateLocationResponse"> & {
+ /**
+ * Whether the deletion was successful.
+ *
+ * @generated from field: bool success = 1;
+ */
+ success: boolean;
+};
+
+/**
+ * Describes the message openstatus.private_location.v1.DeletePrivateLocationResponse.
+ * Use `create(DeletePrivateLocationResponseSchema)` to create a new message.
+ */
+export const DeletePrivateLocationResponseSchema: GenMessage<DeletePrivateLocationResponse> = /*@__PURE__*/
+ messageDesc(file_openstatus_private_location_v1_service, 9);
+
+/**
+ * PrivateLocationService provides CRUD operations for private locations —
+ * self-hosted checker agents that run monitors from your own network.
+ *
+ * @generated from service openstatus.private_location.v1.PrivateLocationService
+ */
+export const PrivateLocationService: GenService<{
+ /**
+ * CreatePrivateLocation creates a new private location and returns its
+ * generated agent token.
+ *
+ * @generated from rpc openstatus.private_location.v1.PrivateLocationService.CreatePrivateLocation
+ */
+ createPrivateLocation: {
+ methodKind: "unary";
+ input: typeof CreatePrivateLocationRequestSchema;
+ output: typeof CreatePrivateLocationResponseSchema;
+ },
+ /**
+ * GetPrivateLocation retrieves a single private location by ID, including
+ * its agent token.
+ *
+ * @generated from rpc openstatus.private_location.v1.PrivateLocationService.GetPrivateLocation
+ */
+ getPrivateLocation: {
+ methodKind: "unary";
+ input: typeof GetPrivateLocationRequestSchema;
+ output: typeof GetPrivateLocationResponseSchema;
+ },
+ /**
+ * ListPrivateLocations returns a paginated list of private location
+ * summaries. Agent tokens are not included - use GetPrivateLocation.
+ *
+ * @generated from rpc openstatus.private_location.v1.PrivateLocationService.ListPrivateLocations
+ */
+ listPrivateLocations: {
+ methodKind: "unary";
+ input: typeof ListPrivateLocationsRequestSchema;
+ output: typeof ListPrivateLocationsResponseSchema;
+ },
+ /**
+ * UpdatePrivateLocation updates a private location.
+ *
+ * @generated from rpc openstatus.private_location.v1.PrivateLocationService.UpdatePrivateLocation
+ */
+ updatePrivateLocation: {
+ methodKind: "unary";
+ input: typeof UpdatePrivateLocationRequestSchema;
+ output: typeof UpdatePrivateLocationResponseSchema;
+ },
+ /**
+ * DeletePrivateLocation removes a private location.
+ *
+ * @generated from rpc openstatus.private_location.v1.PrivateLocationService.DeletePrivateLocation
+ */
+ deletePrivateLocation: {
+ methodKind: "unary";
+ input: typeof DeletePrivateLocationRequestSchema;
+ output: typeof DeletePrivateLocationResponseSchema;
+ },
+}> = /*@__PURE__*/
+ serviceDesc(file_openstatus_private_location_v1_service, 0);
+
diff --git a/packages/proto/package.json b/packages/proto/package.json
index a9773b68e..be04f46c3 100644
--- a/packages/proto/package.json
+++ b/packages/proto/package.json
@@ -32,6 +32,10 @@
"./notification/v1": {
"import": "./gen/ts/openstatus/notification/v1/index.ts",
"types": "./gen/ts/openstatus/notification/v1/index.ts"
+ },
+ "./private_location/v1": {
+ "import": "./gen/ts/openstatus/private_location/v1/index.ts",
+ "types": "./gen/ts/openstatus/private_location/v1/index.ts"
}
},
"scripts": {
diff --git a/packages/services/src/agent-tools/index.ts b/packages/services/src/agent-tools/index.ts
index 71a81abe0..72ebc266f 100644
--- a/packages/services/src/agent-tools/index.ts
+++ b/packages/services/src/agent-tools/index.ts
@@ -14,6 +14,7 @@ import {
import { listNotificationsTool } from "./notification";
import { listStatusPagesTool } from "./page";
import { listPageComponentsTool } from "./page-component";
+import { listPrivateLocationsTool } from "./private-location";
import {
addStatusReportUpdateTool,
createStatusReportTool,
@@ -37,6 +38,7 @@ export {
export { listNotificationsTool } from "./notification";
export { listStatusPagesTool } from "./page";
export { listPageComponentsTool } from "./page-component";
+export { listPrivateLocationsTool } from "./private-location";
export {
addStatusReportUpdateTool,
createStatusReportTool,
@@ -87,6 +89,7 @@ export const agentTools = {
list_response_logs: listResponseLogsTool,
get_response_log: getResponseLogTool,
list_notifications: listNotificationsTool,
+ list_private_locations: listPrivateLocationsTool,
list_audit_logs: listAuditLogsTool,
get_audit_log: getAuditLogTool,
search_docs: searchDocsTool,
diff --git a/packages/services/src/agent-tools/private-location.ts b/packages/services/src/agent-tools/private-location.ts
new file mode 100644
index 000000000..003cda944
--- /dev/null
+++ b/packages/services/src/agent-tools/private-location.ts
@@ -0,0 +1,85 @@
+import { z } from "zod";
+
+import { listPrivateLocations } from "../private-location";
+import type { AgentTool } from "./types";
+
+const PER_PAGE_DEFAULT = 50;
+const PER_PAGE_MAX = 100;
+
+const ListPrivateLocationsInputShape = z.object({
+ page: z
+ .number()
+ .int()
+ .min(1)
+ .default(1)
+ .describe("1-indexed page number (default 1)."),
+ perPage: z
+ .number()
+ .int()
+ .min(1)
+ .max(PER_PAGE_MAX)
+ .default(PER_PAGE_DEFAULT)
+ .describe(
+ `Items per page (default ${PER_PAGE_DEFAULT}, max ${PER_PAGE_MAX}).`,
+ ),
+});
+
+// `token` is omitted — it's the agent's bearer credential, and possession of it
+// grants access to monitor configs including secret request headers.
+const ListPrivateLocationsOutput = z.object({
+ items: z.array(
+ z.object({
+ id: z.number().int(),
+ name: z.string(),
+ monitorIds: z.array(z.number().int()),
+ lastSeenAt: z.string().nullable(),
+ createdAt: z.string().nullable(),
+ updatedAt: z.string().nullable(),
+ }),
+ ),
+ pagination: z.object({
+ page: z.number().int(),
+ perPage: z.number().int(),
+ totalSize: z.number().int(),
+ totalPages: z.number().int(),
+ }),
+});
+
+export const listPrivateLocationsTool: AgentTool<
+ z.infer<typeof ListPrivateLocationsInputShape>,
+ z.infer<typeof ListPrivateLocationsOutput>
+> = {
+ name: "list_private_locations",
+ description:
+ "List private locations (self-hosted checker agents) in this workspace, with the monitors each one runs and when it last reported in. Read-only — agent tokens are NOT exposed. Use `lastSeenAt` to tell whether an agent is still alive before blaming a monitor for missing checks.",
+ scope: "read",
+ destructive: false,
+ inputSchema: ListPrivateLocationsInputShape,
+ outputSchema: ListPrivateLocationsOutput,
+ async run({ ctx, input }) {
+ const { page, perPage } = input;
+ const result = await listPrivateLocations({
+ ctx,
+ input: {
+ limit: perPage,
+ offset: (page - 1) * perPage,
+ },
+ });
+ return {
+ items: result.items.map((location) => ({
+ id: location.id,
+ name: location.name,
+ monitorIds: location.monitors.map((m) => m.id),
+ lastSeenAt: location.lastSeenAt?.toISOString() ?? null,
+ createdAt: location.createdAt?.toISOString() ?? null,
+ updatedAt: location.updatedAt?.toISOString() ?? null,
+ })),
+ pagination: {
+ page,
+ perPage,
+ totalSize: result.totalSize,
+ totalPages: Math.max(1, Math.ceil(result.totalSize / perPage)),
+ },
+ };
+ },
+};
diff --git a/packages/services/src/private-location/__tests__/private-location.test.ts b/packages/services/src/private-location/__tests__/private-location.test.ts
new file mode 100644
index 000000000..93e3cafd6
--- /dev/null
+++ b/packages/services/src/private-location/__tests__/private-location.test.ts
@@ -0,0 +1,591 @@
+import { and, db, eq } from "@openstatus/db";
+import {
+ monitor,
+ privateLocation,
+ privateLocationToMonitors,
+ selectWorkspaceSchema,
+ workspace,
+} from "@openstatus/db/src/schema";
+import { getLimits } from "@openstatus/db/src/schema/plan/utils";
+import { expect } from "@std/expect";
+import { afterAll, beforeAll, describe, test } from "@std/testing/bdd";
+
+import { SEEDED_WORKSPACE_TEAM_ID } from "../../../test/fixtures";
+import {
+ expectAuditRow,
+ loadSeededWorkspace,
+ makeApiKeyCtx,
+ makeUserCtx,
+ readAuditLog,
+ withTestTransaction,
+} from "../../../test/helpers";
+import type { ServiceContext } from "../../context";
+import { ForbiddenError, NotFoundError } from "../../errors";
+import { createPrivateLocation } from "../create";
+import { deletePrivateLocation } from "../delete";
+import { getPrivateLocation } from "../get";
+import { listPrivateLocations } from "../list";
+import { updatePrivateLocation } from "../update";
+
+const TEST_PREFIX = "svc-private-location-test";
+
+let teamCtx: ServiceContext;
+let teamMonitorId: number;
+let secondMonitorId: number;
+let deletedMonitorId: number;
+let otherWorkspaceMonitorId: number;
+let otherWorkspaceId: number;
+
+const OTHER_WS_SLUG = `${TEST_PREFIX}-other-ws`;
+
+beforeAll(async () => {
+ const team = await loadSeededWorkspace(SEEDED_WORKSPACE_TEAM_ID);
+ teamCtx = makeUserCtx(team, { userId: 1 });
+
+ const mk = async (name: string, workspaceId: number, deleted?: boolean) => {
+ const row = await db
+ .insert(monitor)
+ .values({
+ name,
+ workspaceId,
+ url: "https://example.com",
+ periodicity: "10m",
+ deletedAt: deleted ? new Date() : null,
+ })
+ .returning()
+ .get();
+ return row.id;
+ };
+
+ teamMonitorId = await mk(`${TEST_PREFIX}-monitor`, teamCtx.workspace.id);
+ secondMonitorId = await mk(`${TEST_PREFIX}-monitor-2`, teamCtx.workspace.id);
+ deletedMonitorId = await mk(
+ `${TEST_PREFIX}-monitor-deleted`,
+ teamCtx.workspace.id,
+ true,
+ );
+
+ await db
+ .delete(workspace)
+ .where(eq(workspace.slug, OTHER_WS_SLUG))
+ .catch(() => undefined);
+ const otherRow = await db
+ .insert(workspace)
+ .values({
+ slug: OTHER_WS_SLUG,
+ name: `${TEST_PREFIX}-other`,
+ plan: "team",
+ limits: JSON.stringify(getLimits("team")),
+ })
+ .returning()
+ .get();
+ const otherWs = selectWorkspaceSchema.parse(otherRow);
+ otherWorkspaceId = otherWs.id;
+ otherWorkspaceMonitorId = await mk(
+ `${TEST_PREFIX}-other-monitor`,
+ otherWs.id,
+ );
+});
+
+afterAll(async () => {
+ for (const id of [
+ teamMonitorId,
+ secondMonitorId,
+ deletedMonitorId,
+ otherWorkspaceMonitorId,
+ ]) {
+ await db.delete(monitor).where(eq(monitor.id, id));
+ }
+ await db.delete(workspace).where(eq(workspace.slug, OTHER_WS_SLUG));
+});
+
+describe("createPrivateLocation", () => {
+ test("generates a token when none is supplied", async () => {
+ await withTestTransaction(async (tx) => {
+ const row = await createPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: { name: `${TEST_PREFIX}-generated`, monitors: [] },
+ });
+
+ expect(row.token).toBeTruthy();
+ expect(row.token.length).toBeGreaterThan(20);
+ });
+ });
+
+ test("generates a distinct token per location", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const a = await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-a`, monitors: [] },
+ });
+ const b = await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-b`, monitors: [] },
+ });
+
+ expect(a.token).not.toBe(b.token);
+ });
+ });
+
+ test("honors a caller-supplied token", async () => {
+ await withTestTransaction(async (tx) => {
+ const row = await createPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: {
+ name: `${TEST_PREFIX}-supplied`,
+ token: "caller-chosen-token",
+ monitors: [],
+ },
+ });
+
+ expect(row.token).toBe("caller-chosen-token");
+ });
+ });
+
+ test("attaches monitors and audits the create", async () => {
+ await withTestTransaction(async (tx) => {
+ const row = await createPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: {
+ name: `${TEST_PREFIX}-with-monitors`,
+ monitors: [teamMonitorId],
+ },
+ });
+
+ const links = await tx
+ .select()
+ .from(privateLocationToMonitors)
+ .where(eq(privateLocationToMonitors.privateLocationId, row.id))
+ .all();
+ expect(links.map((l) => l.monitorId)).toEqual([teamMonitorId]);
+
+ await expectAuditRow({
+ workspaceId: teamCtx.workspace.id,
+ action: "private_location.create",
+ entityType: "private_location",
+ entityId: row.id,
+ db: tx,
+ });
+ });
+ });
+
+ test("dedupes duplicate monitor ids", async () => {
+ await withTestTransaction(async (tx) => {
+ const row = await createPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: {
+ name: `${TEST_PREFIX}-dupes`,
+ monitors: [teamMonitorId, teamMonitorId, teamMonitorId],
+ },
+ });
+
+ const links = await tx
+ .select()
+ .from(privateLocationToMonitors)
+ .where(eq(privateLocationToMonitors.privateLocationId, row.id))
+ .all();
+ expect(links.length).toBe(1);
+ });
+ });
+
+ test("rejects a monitor from another workspace", async () => {
+ await withTestTransaction(async (tx) => {
+ await expect(
+ createPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: {
+ name: `${TEST_PREFIX}-foreign`,
+ monitors: [otherWorkspaceMonitorId],
+ },
+ }),
+ ).rejects.toBeInstanceOf(ForbiddenError);
+ });
+ });
+
+ test("rejects a soft-deleted monitor", async () => {
+ await withTestTransaction(async (tx) => {
+ await expect(
+ createPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: {
+ name: `${TEST_PREFIX}-deleted-monitor`,
+ monitors: [deletedMonitorId],
+ },
+ }),
+ ).rejects.toBeInstanceOf(ForbiddenError);
+ });
+ });
+
+ test("rejects read-only actor", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = {
+ ...makeApiKeyCtx(teamCtx.workspace, {
+ keyId: "k",
+ userId: 1,
+ scopes: ["read"],
+ }),
+ db: tx,
+ };
+ await expect(
+ createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-readonly`, monitors: [] },
+ }),
+ ).rejects.toBeInstanceOf(ForbiddenError);
+ });
+ });
+});
+
+describe("updatePrivateLocation", () => {
+ const seed = async (
+ tx: Parameters<Parameters<typeof withTestTransaction>[0]>[0],
+ monitors: number[] = [],
+ ) =>
+ createPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: { name: `${TEST_PREFIX}-seed`, monitors },
+ });
+
+ test("updates the name and leaves associations untouched", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await seed(tx, [teamMonitorId]);
+
+ const updated = await updatePrivateLocation({
+ ctx,
+ input: { id: created.id, name: `${TEST_PREFIX}-renamed` },
+ });
+ expect(updated.name).toBe(`${TEST_PREFIX}-renamed`);
+
+ const links = await tx
+ .select()
+ .from(privateLocationToMonitors)
+ .where(eq(privateLocationToMonitors.privateLocationId, created.id))
+ .all();
+ expect(links.map((l) => l.monitorId)).toEqual([teamMonitorId]);
+ });
+ });
+
+ test("replaces associations without touching the name", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await seed(tx, [teamMonitorId]);
+
+ const updated = await updatePrivateLocation({
+ ctx,
+ input: { id: created.id, monitors: [secondMonitorId] },
+ });
+ expect(updated.name).toBe(created.name);
+
+ const links = await tx
+ .select()
+ .from(privateLocationToMonitors)
+ .where(eq(privateLocationToMonitors.privateLocationId, created.id))
+ .all();
+ expect(links.map((l) => l.monitorId)).toEqual([secondMonitorId]);
+ });
+ });
+
+ test("clears associations when monitors is an empty array", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await seed(tx, [teamMonitorId]);
+
+ await updatePrivateLocation({
+ ctx,
+ input: { id: created.id, monitors: [] },
+ });
+
+ const links = await tx
+ .select()
+ .from(privateLocationToMonitors)
+ .where(eq(privateLocationToMonitors.privateLocationId, created.id))
+ .all();
+ expect(links.length).toBe(0);
+ });
+ });
+
+ test("emits no audit row when nothing changes", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await seed(tx, [teamMonitorId]);
+
+ await updatePrivateLocation({ ctx, input: { id: created.id } });
+
+ const rows = await readAuditLog({
+ workspaceId: teamCtx.workspace.id,
+ entityType: "private_location",
+ entityId: String(created.id),
+ db: tx,
+ });
+ expect(rows.some((r) => r.action === "private_location.update")).toBe(
+ false,
+ );
+ });
+ });
+
+ test("audits a real update", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await seed(tx);
+
+ await updatePrivateLocation({
+ ctx,
+ input: { id: created.id, name: `${TEST_PREFIX}-audited` },
+ });
+
+ await expectAuditRow({
+ workspaceId: teamCtx.workspace.id,
+ action: "private_location.update",
+ entityType: "private_location",
+ entityId: created.id,
+ db: tx,
+ });
+ });
+ });
+
+ test("rejects a soft-deleted monitor", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await seed(tx);
+
+ await expect(
+ updatePrivateLocation({
+ ctx,
+ input: { id: created.id, monitors: [deletedMonitorId] },
+ }),
+ ).rejects.toBeInstanceOf(ForbiddenError);
+ });
+ });
+
+ test("throws NotFoundError for an unknown id", async () => {
+ await withTestTransaction(async (tx) => {
+ await expect(
+ updatePrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: { id: 999_999_999, name: "nope" },
+ }),
+ ).rejects.toBeInstanceOf(NotFoundError);
+ });
+ });
+
+ test("rejects read-only actor", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = {
+ ...makeApiKeyCtx(teamCtx.workspace, {
+ keyId: "k",
+ userId: 1,
+ scopes: ["read"],
+ }),
+ db: tx,
+ };
+ await expect(
+ updatePrivateLocation({ ctx, input: { id: 1, name: "nope" } }),
+ ).rejects.toBeInstanceOf(ForbiddenError);
+ });
+ });
+});
+
+describe("getPrivateLocation", () => {
+ test("returns the location with its monitors", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-get`, monitors: [teamMonitorId] },
+ });
+
+ const found = await getPrivateLocation({
+ ctx,
+ input: { id: created.id },
+ });
+ expect(found.id).toBe(created.id);
+ expect(found.token).toBe(created.token);
+ expect(found.monitors.map((m) => m.id)).toEqual([teamMonitorId]);
+ });
+ });
+
+ test("throws NotFoundError for an unknown id", async () => {
+ await withTestTransaction(async (tx) => {
+ await expect(
+ getPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: { id: 999_999_999 },
+ }),
+ ).rejects.toBeInstanceOf(NotFoundError);
+ });
+ });
+
+ test("throws NotFoundError for another workspace's location", async () => {
+ await withTestTransaction(async (tx) => {
+ const other = await tx
+ .insert(privateLocation)
+ .values({
+ name: `${TEST_PREFIX}-foreign-loc`,
+ token: "foreign-token",
+ workspaceId: otherWorkspaceId,
+ })
+ .returning()
+ .get();
+
+ await expect(
+ getPrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: { id: other.id },
+ }),
+ ).rejects.toBeInstanceOf(NotFoundError);
+ });
+ });
+});
+
+describe("listPrivateLocations", () => {
+ test("returns items and a workspace-scoped totalSize", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const before = await listPrivateLocations({ ctx });
+
+ await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-list-1`, monitors: [teamMonitorId] },
+ });
+ await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-list-2`, monitors: [] },
+ });
+
+ const after = await listPrivateLocations({ ctx });
+ expect(after.totalSize).toBe(before.totalSize + 2);
+ expect(
+ after.items.every((i) => i.workspaceId === teamCtx.workspace.id),
+ ).toBe(true);
+ });
+ });
+
+ test("applies limit and offset over a stable ordering", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-page-1`, monitors: [] },
+ });
+ await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-page-2`, monitors: [] },
+ });
+
+ const firstPage = await listPrivateLocations({
+ ctx,
+ input: { limit: 1, offset: 0 },
+ });
+ const secondPage = await listPrivateLocations({
+ ctx,
+ input: { limit: 1, offset: 1 },
+ });
+
+ expect(firstPage.items.length).toBe(1);
+ expect(secondPage.items.length).toBe(1);
+ expect(firstPage.items[0].id).not.toBe(secondPage.items[0].id);
+ });
+ });
+});
+
+describe("deletePrivateLocation", () => {
+ test("removes the row, cascades links, and audits", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = { ...teamCtx, db: tx };
+ const created = await createPrivateLocation({
+ ctx,
+ input: { name: `${TEST_PREFIX}-delete`, monitors: [teamMonitorId] },
+ });
+
+ await deletePrivateLocation({ ctx, input: { id: created.id } });
+
+ const remaining = await tx
+ .select()
+ .from(privateLocation)
+ .where(eq(privateLocation.id, created.id))
+ .all();
+ expect(remaining.length).toBe(0);
+
+ const links = await tx
+ .select()
+ .from(privateLocationToMonitors)
+ .where(eq(privateLocationToMonitors.privateLocationId, created.id))
+ .all();
+ expect(links.length).toBe(0);
+
+ await expectAuditRow({
+ workspaceId: teamCtx.workspace.id,
+ action: "private_location.delete",
+ entityType: "private_location",
+ entityId: created.id,
+ db: tx,
+ });
+ });
+ });
+
+ test("is idempotent for an unknown id", async () => {
+ await withTestTransaction(async (tx) => {
+ await deletePrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: { id: 999_999_999 },
+ });
+
+ const rows = await readAuditLog({
+ workspaceId: teamCtx.workspace.id,
+ entityType: "private_location",
+ entityId: "999999999",
+ db: tx,
+ });
+ expect(rows.length).toBe(0);
+ });
+ });
+
+ test("does not delete another workspace's location", async () => {
+ await withTestTransaction(async (tx) => {
+ const other = await tx
+ .insert(privateLocation)
+ .values({
+ name: `${TEST_PREFIX}-foreign-delete`,
+ token: "foreign-token-2",
+ workspaceId: otherWorkspaceId,
+ })
+ .returning()
+ .get();
+
+ await deletePrivateLocation({
+ ctx: { ...teamCtx, db: tx },
+ input: { id: other.id },
+ });
+
+ const remaining = await tx
+ .select()
+ .from(privateLocation)
+ .where(
+ and(
+ eq(privateLocation.id, other.id),
+ eq(privateLocation.workspaceId, otherWorkspaceId),
+ ),
+ )
+ .all();
+ expect(remaining.length).toBe(1);
+ });
+ });
+
+ test("rejects read-only actor", async () => {
+ await withTestTransaction(async (tx) => {
+ const ctx = {
+ ...makeApiKeyCtx(teamCtx.workspace, {
+ keyId: "k",
+ userId: 1,
+ scopes: ["read"],
+ }),
+ db: tx,
+ };
+ await expect(
+ deletePrivateLocation({ ctx, input: { id: 1 } }),
+ ).rejects.toBeInstanceOf(ForbiddenError);
+ });
+ });
+});
diff --git a/packages/services/src/private-location/create.ts b/packages/services/src/private-location/create.ts
index b590a3ea7..22d2e98d2 100644
--- a/packages/services/src/private-location/create.ts
+++ b/packages/services/src/private-location/create.ts
@@ -28,6 +28,9 @@ export async function createPrivateLocation(args: {
requireScope(ctx, "write");
const input = CreatePrivateLocationInput.parse(args.input);
+ // Callers that can't mint their own credential (the public API) omit it.
+ const token = input.token ?? crypto.randomUUID();
+
// The pivot table has no UNIQUE (private_location_id, monitor_id)
// constraint, so duplicate input ids would silently produce duplicate
// FK rows. Dedupe before insert; the audit snapshot follows suit.
@@ -44,7 +47,7 @@ export async function createPrivateLocation(args: {
.insert(privateLocation)
.values({
name: input.name,
- token: input.token,
+ token,
workspaceId: ctx.workspace.id,
})
.returning()
diff --git a/packages/services/src/private-location/get.ts b/packages/services/src/private-location/get.ts
new file mode 100644
index 000000000..5df3be235
--- /dev/null
+++ b/packages/services/src/private-location/get.ts
@@ -0,0 +1,41 @@
+import { and, eq } from "@openstatus/db";
+import { privateLocation } from "@openstatus/db/src/schema";
+
+import { type ServiceContext, getReadDb } from "../context";
+import { NotFoundError } from "../errors";
+import { GetPrivateLocationInput } from "./schemas";
+
+/**
+ * Fetch one private location in the caller's workspace, flattened the same
+ * way `listPrivateLocations` flattens its items.
+ *
+ * Return type is deliberately inferred — see the note in `list.ts`.
+ */
+export async function getPrivateLocation(args: {
+ ctx: ServiceContext;
+ input: GetPrivateLocationInput;
+}) {
+ const input = GetPrivateLocationInput.parse(args.input);
+ const db = getReadDb(args.ctx);
+
+ const row = await db.query.privateLocation.findFirst({
+ where: and(
+ eq(privateLocation.id, input.id),
+ eq(privateLocation.workspaceId, args.ctx.workspace.id),
+ ),
+ with: {
+ privateLocationToMonitors: {
+ with: { monitor: true },
+ },
+ },
+ });
+
+ if (!row) throw new NotFoundError("private_location", input.id);
+
+ return {
+ ...row,
+ monitors: row.privateLocationToMonitors
+ .map((link) => link.monitor)
+ .filter((m) => m !== null),
+ };
+}
diff --git a/packages/services/src/private-location/index.ts b/packages/services/src/private-location/index.ts
index c74e86825..83fb2d5ec 100644
--- a/packages/services/src/private-location/index.ts
+++ b/packages/services/src/private-location/index.ts
@@ -1,10 +1,12 @@
export { createPrivateLocation } from "./create";
export { deletePrivateLocation } from "./delete";
+export { getPrivateLocation } from "./get";
export { listPrivateLocations } from "./list";
export { updatePrivateLocation } from "./update";
export {
CreatePrivateLocationInput,
DeletePrivateLocationInput,
+ GetPrivateLocationInput,
ListPrivateLocationsInput,
UpdatePrivateLocationInput,
} from "./schemas";
diff --git a/packages/services/src/private-location/internal.ts b/packages/services/src/private-location/internal.ts
index 9407f5466..50ee14c75 100644
--- a/packages/services/src/private-location/internal.ts
+++ b/packages/services/src/private-location/internal.ts
@@ -1,14 +1,15 @@
-import { and, eq, inArray } from "@openstatus/db";
+import { and, eq, inArray, isNull } from "@openstatus/db";
import { monitor } from "@openstatus/db/src/schema";
import type { DB } from "../context";
import { ForbiddenError } from "../errors";
/**
- * Ensure every id in `monitorIds` belongs to the given workspace. No-op
- * when the list is empty. Throws `ForbiddenError` (not `NotFound`) to
- * match the legacy router's `FORBIDDEN` response — surfacing "this id
- * doesn't exist" vs. "this id isn't yours" would leak workspace state.
+ * Ensure every id in `monitorIds` belongs to the given workspace and is not
+ * soft-deleted. No-op when the list is empty. Throws `ForbiddenError` (not
+ * `NotFound`) to match the legacy router's `FORBIDDEN` response — surfacing
+ * "this id doesn't exist" vs. "this id isn't yours" would leak workspace
+ * state.
*/
export async function assertMonitorsInWorkspace(args: {
tx: DB;
@@ -24,6 +25,7 @@ export async function assertMonitorsInWorkspace(args: {
where: and(
eq(monitor.workspaceId, workspaceId),
inArray(monitor.id, uniqueIds),
+ isNull(monitor.deletedAt),
),
});
if (valid.length !== uniqueIds.length) {
diff --git a/packages/services/src/private-location/list.ts b/packages/services/src/private-location/list.ts
index 8a5b73a4a..6ad121428 100644
--- a/packages/services/src/private-location/list.ts
+++ b/packages/services/src/private-location/list.ts
@@ -1,9 +1,11 @@
-import { eq } from "@openstatus/db";
+import { count, desc, eq } from "@openstatus/db";
import { privateLocation } from "@openstatus/db/src/schema";
import { type ServiceContext, getReadDb } from "../context";
import { ListPrivateLocationsInput } from "./schemas";
+const LIMIT_DEFAULT = 50;
+
/**
* List private locations in the caller's workspace, each one flattened to
* include the monitors it's attached to (the relational join's `monitor`
@@ -18,7 +20,7 @@ export async function listPrivateLocations(args: {
ctx: ServiceContext;
input?: ListPrivateLocationsInput;
}) {
- ListPrivateLocationsInput.parse(args.input ?? {});
+ const input = ListPrivateLocationsInput.parse(args.input ?? {});
const db = getReadDb(args.ctx);
const rows = await db.query.privateLocation.findMany({
@@ -28,12 +30,24 @@ export async function listPrivateLocations(args: {
with: { monitor: true },
},
},
+ orderBy: desc(privateLocation.id),
+ limit: input.limit ?? LIMIT_DEFAULT,
+ offset: input.offset ?? 0,
});
- return rows.map((row) => ({
- ...row,
- monitors: row.privateLocationToMonitors
- .map((link) => link.monitor)
- .filter((m) => m !== null),
- }));
+ const total = await db
+ .select({ count: count() })
+ .from(privateLocation)
+ .where(eq(privateLocation.workspaceId, args.ctx.workspace.id))
+ .get();
+
+ return {
+ items: rows.map((row) => ({
+ ...row,
+ monitors: row.privateLocationToMonitors
+ .map((link) => link.monitor)
+ .filter((m) => m !== null),
+ })),
+ totalSize: total?.count ?? 0,
+ };
}
diff --git a/packages/services/src/private-location/schemas.ts b/packages/services/src/private-location/schemas.ts
index 5b308103e..1db4ae5c6 100644
--- a/packages/services/src/private-location/schemas.ts
+++ b/packages/services/src/private-location/schemas.ts
@@ -1,6 +1,11 @@
import { z } from "zod";
-export const ListPrivateLocationsInput = z.object({}).strict();
+export const ListPrivateLocationsInput = z
+ .object({
+ limit: z.number().int().min(1).max(100).optional(),
+ offset: z.number().int().min(0).optional(),
+ })
+ .strict();
export type ListPrivateLocationsInput = z.infer<
typeof ListPrivateLocationsInput
>;
@@ -9,7 +14,7 @@ const monitorIds = z.array(z.number().int().positive());
export const CreatePrivateLocationInput = z.object({
name: z.string().min(1),
- token: z.string().min(1),
+ token: z.string().min(1).optional(),
monitors: monitorIds,
});
export type CreatePrivateLocationInput = z.infer<
@@ -18,13 +23,16 @@ export type CreatePrivateLocationInput = z.infer<
export const UpdatePrivateLocationInput = z.object({
id: z.number().int(),
- name: z.string().min(1),
- monitors: monitorIds,
+ name: z.string().min(1).optional(),
+ monitors: monitorIds.optional(),
});
export type UpdatePrivateLocationInput = z.infer<
typeof UpdatePrivateLocationInput
>;
+export const GetPrivateLocationInput = z.object({ id: z.number().int() });
+export type GetPrivateLocationInput = z.infer<typeof GetPrivateLocationInput>;
+
export const DeletePrivateLocationInput = z.object({ id: z.number().int() });
export type DeletePrivateLocationInput = z.infer<
typeof DeletePrivateLocationInput
diff --git a/packages/services/src/private-location/update.ts b/packages/services/src/private-location/update.ts
index 096177c95..adc335611 100644
--- a/packages/services/src/private-location/update.ts
+++ b/packages/services/src/private-location/update.ts
@@ -14,12 +14,8 @@ import { assertMonitorsInWorkspace } from "./internal";
import { UpdatePrivateLocationInput } from "./schemas";
/**
- * Replace the name and monitor associations of a private location.
- *
- * `updatedAt` is set explicitly — same as the legacy router.
- * Associations are bulk-replaced: delete-all followed by insert-all for
- * the new set. The delete is unconditional inside the workspace-scoped
- * tx, so there's no opportunity for a stale row to leak through.
+ * Patch a private location. Omitted fields are left untouched; passing an
+ * empty `monitors` array clears every association.
*/
export async function updatePrivateLocation(args: {
ctx: ServiceContext;
@@ -32,7 +28,9 @@ export async function updatePrivateLocation(args: {
// The pivot table has no UNIQUE (private_location_id, monitor_id)
// constraint, so duplicate input ids would silently produce duplicate
// FK rows. Dedupe before insert; the audit snapshot follows suit.
- const monitorIds = Array.from(new Set(input.monitors));
+ const monitorIds = input.monitors
+ ? Array.from(new Set(input.monitors))
+ : undefined;
return withTransaction(ctx, async (tx) => {
const existing = await tx.query.privateLocation.findFirst({
@@ -49,15 +47,21 @@ export async function updatePrivateLocation(args: {
throw new NotFoundError("private_location", input.id);
}
- await assertMonitorsInWorkspace({
- tx,
- workspaceId: ctx.workspace.id,
- monitorIds,
- });
+ if (monitorIds) {
+ await assertMonitorsInWorkspace({
+ tx,
+ workspaceId: ctx.workspace.id,
+ monitorIds,
+ });
+ }
const row = await tx
.update(privateLocation)
- .set({ name: input.name, updatedAt: new Date() })
+ .set(
+ input.name !== undefined
+ ? { name: input.name, updatedAt: new Date() }
+ : { updatedAt: new Date() },
+ )
.where(
and(
eq(privateLocation.id, input.id),
@@ -74,37 +78,40 @@ export async function updatePrivateLocation(args: {
// undefined`. Re-throw NotFound so the failure mode stays sane.
if (!row) throw new NotFoundError("private_location", input.id);
- await tx
- .delete(privateLocationToMonitors)
- .where(eq(privateLocationToMonitors.privateLocationId, row.id));
+ if (monitorIds) {
+ await tx
+ .delete(privateLocationToMonitors)
+ .where(eq(privateLocationToMonitors.privateLocationId, row.id));
- if (monitorIds.length > 0) {
- await tx.insert(privateLocationToMonitors).values(
- monitorIds.map((monitorId) => ({
- privateLocationId: row.id,
- monitorId,
- })),
- );
+ if (monitorIds.length > 0) {
+ await tx.insert(privateLocationToMonitors).values(
+ monitorIds.map((monitorId) => ({
+ privateLocationId: row.id,
+ monitorId,
+ })),
+ );
+ }
}
const { privateLocationToMonitors: beforeLinks, ...beforeRow } = existing;
const beforeParsed = selectPrivateLocationSchema.parse(beforeRow);
const afterParsed = selectPrivateLocationSchema.parse(row);
+ const beforeMonitorIds = beforeLinks
+ .map((l) => l.monitorId)
+ .filter((id): id is number => id !== null)
+ .sort((a, b) => a - b);
+
await emitAudit(tx, ctx, {
action: "private_location.update",
entityType: "private_location",
entityId: afterParsed.id,
- before: {
- ...beforeParsed,
- monitorIds: beforeLinks
- .map((l) => l.monitorId)
- .filter((id): id is number => id !== null)
- .sort((a, b) => a - b),
- },
+ before: { ...beforeParsed, monitorIds: beforeMonitorIds },
after: {
...afterParsed,
- monitorIds: [...monitorIds].sort((a, b) => a - b),
+ monitorIds: monitorIds
+ ? [...monitorIds].sort((a, b) => a - b)
+ : beforeMonitorIds,
},
});