Skip to content
beeps.dev beeps.dev

Managing Alerts

Manage alerts throughout their lifecycle.

Listing All Alerts

Section titled “Listing All Alerts”
import { BeepsClient } from "@beepsdev/sdk";


const client = new BeepsClient({
  apiKey: process.env.BEEPS_API_KEY,
});


const alerts = await client.alert.list();


console.log(`Found ${alerts.length} total alerts`);
alerts.forEach((alert) => {
  console.log(`[${alert.severity}] ${alert.title}`);
});

Listing Active Alerts

Section titled “Listing Active Alerts”
const activeAlerts = await client.alert.listActive();


console.log(`${activeAlerts.length} active alerts need attention`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.listActiveSafe();


if (result.error) {
  console.error("Failed to list alerts:", result.error.message);
} else {
  console.log(`Active alerts: ${result.data.length}`);
}

Listing Resolved Alerts

Section titled “Listing Resolved Alerts”
const resolvedAlerts = await client.alert.listResolved();


console.log(`${resolvedAlerts.length} alerts have been resolved`);

Getting a Specific Alert

Section titled “Getting a Specific Alert”
const alert = await client.alert.get("alr_abc123");


console.log(`Title: ${alert.title}`);
console.log(`Severity: ${alert.severity}`);
console.log(`Status: ${alert.resolvedAt ? "Resolved" : "Active"}`);

Responding to an Alert

Section titled “Responding to an Alert”

Signal that you’re working on an alert. This creates a responder record.

const responder = await client.alert.onIt("alr_abc123", {
  userId: "usr_alice",
});


console.log(`${responder.userId} is on it (status: ${responder.status})`);
console.log(`Joined at ${responder.joinedAt}`);

If userId is not provided, the authenticated user is used:

const responder = await client.alert.onIt("alr_abc123");

Safe Method

Section titled “Safe Method”
const result = await client.alert.onItSafe("alr_abc123", {
  userId: "usr_alice",
});


if (result.error) {
  console.error("Failed to respond:", result.error.message);
} else {
  console.log(`Responder joined: ${result.data.id}`);
}

Listing Responders

Section titled “Listing Responders”
const responders = await client.alert.listResponders("alr_abc123");


responders.forEach((r) => {
  console.log(`${r.userId || r.integrationId} — ${r.status}`);
  if (r.prUrl) {
    console.log(`  PR: ${r.prUrl}`);
  }
});

Safe Method

Section titled “Safe Method”
const result = await client.alert.listRespondersSafe("alr_abc123");


if (result.error) {
  console.error("Failed to list responders:", result.error.message);
} else {
  console.log(`${result.data.length} responders`);
}

Updating Responder Status

Section titled “Updating Responder Status”

Mark a responder as done or dropped. You can optionally attach a PR URL when completing work.

const updated = await client.alert.updateResponderStatus(
  "alr_abc123",
  "rsp_def456",
  {
    status: "done",
    prUrl: "https://github.com/org/repo/pull/42",
  },
);


console.log(`Responder status: ${updated.status}`);
console.log(`Completed at: ${updated.completedAt}`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.updateResponderStatusSafe(
  "alr_abc123",
  "rsp_def456",
  { status: "done" },
);


if (result.error) {
  console.error("Failed to update:", result.error.message);
} else {
  console.log("Responder marked as done");
}

Assigning an Alert

Section titled “Assigning an Alert”
const assigned = await client.alert.assign("alr_abc123", "usr_bob");


console.log(`Alert assigned to ${assigned.assignedToUserId}`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.assignSafe("alr_abc123", "usr_bob");


if (result.error) {
  console.error("Failed to assign:", result.error.message);
} else {
  console.log(`Assigned to ${result.data.assignedToUserId}`);
}

Resolving an Alert

Section titled “Resolving an Alert”
const resolved = await client.alert.resolve("alr_abc123");


console.log(`Alert resolved at ${resolved.resolvedAt}`);

Safe Method

Section titled “Safe Method”
const result = await client.alert.resolveSafe("alr_abc123");


if (result.error) {
  console.error("Failed to resolve:", result.error.message);
} else {
  console.log("Alert resolved");
}

Type Definitions

Section titled “Type Definitions”

Alert

Section titled “Alert”
type Alert = {
  id: string;
  organizationId: string;
  webhookId: string;
  title: string;
  message: string | null;
  severity: AlertSeverity;
  source: string;
  externalId: string | null;
  metadata: Record<string, unknown> | null;
  assignedToUserId: string | null;
  resolvedAt: string | null;
  resolvedBy: ResolutionSource | null;
  resolvedByUserId: string | null;
  resolvedByProvider: string | null;
  createdAt: string;
  updatedAt: string;
};

AlertSeverity

Section titled “AlertSeverity”
type AlertSeverity = "critical" | "high" | "medium" | "low" | "info";

ResolutionSource

Section titled “ResolutionSource”
type ResolutionSource = "user" | "monitoring_system";

AlertResponder

Section titled “AlertResponder”
type AlertResponder = {
  id: string;
  alertId: string;
  organizationId: string;
  responderType: ResponderType;
  userId: string | null;
  integrationId: string | null;
  agentSessionId: string | null;
  status: ResponderStatus;
  prUrl: string | null;
  joinedAt: string;
  completedAt: string | null;
};

ResponderType

Section titled “ResponderType”
type ResponderType = "user" | "agent";

ResponderStatus

Section titled “ResponderStatus”
type ResponderStatus = "on_it" | "done" | "dropped";

OnItInput

Section titled “OnItInput”
type OnItInput = {
  userId?: string;
};

UpdateResponderStatusInput

Section titled “UpdateResponderStatusInput”
type UpdateResponderStatusInput = {
  status: "done" | "dropped";
  prUrl?: string;
};

Common Patterns

Section titled “Common Patterns”

Complete Alert Workflow

Section titled “Complete Alert Workflow”
const alertId = "alr_abc123";
const userId = "usr_alice";


const alert = await client.alert.get(alertId);
console.log(`New alert: ${alert.title}`);


const responder = await client.alert.onIt(alertId, { userId });
console.log(`On it: ${responder.status}`);


await client.alert.assign(alertId, userId);
console.log("Assigned to self");


console.log("Working on the issue...");


await client.alert.updateResponderStatus(alertId, responder.id, {
  status: "done",
  prUrl: "https://github.com/org/repo/pull/42",
});
console.log("Responder done");


await client.alert.resolve(alertId);
console.log("Resolved");

Filter Alerts by Severity

Section titled “Filter Alerts by Severity”
const active = await client.alert.listActive();


const critical = active.filter((a) => a.severity === "critical");
const high = active.filter((a) => a.severity === "high");


console.log(`Critical: ${critical.length}`);
console.log(`High: ${high.length}`);

Alert Dashboard

Section titled “Alert Dashboard”
const active = await client.alert.listActive();


const stats = {
  total: active.length,
  assigned: active.filter((a) => a.assignedToUserId).length,
  critical: active.filter((a) => a.severity === "critical").length,
};


console.log("Alert Dashboard:");
console.log(`Total Active: ${stats.total}`);
console.log(`Assigned: ${stats.assigned}`);
console.log(`Critical: ${stats.critical}`);

My Assigned Alerts

Section titled “My Assigned Alerts”
const userId = "usr_alice";
const active = await client.alert.listActive();


const myAlerts = active.filter((a) => a.assignedToUserId === userId);


console.log(`You have ${myAlerts.length} assigned alerts:`);
myAlerts.forEach((alert) => {
  console.log(`- [${alert.severity}] ${alert.title}`);
});

Troubleshooting

Section titled “Troubleshooting”

Alerts not appearing? See Troubleshooting - Alerts Not Appearing.