Managing Relays

Create and manage relays using the SDK and API.

Creating a Relay

import { BeepsClient } from "@beepsdev/sdk";

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

const relay = await client.relay.create({
  name: "Production Alerts",
  description: "Routes critical production incidents",
  externalKey: "prod-alerts", // Optional: use for easier API access
});

console.log(`Created relay: ${relay.id}`);

Safe Method (No Exceptions)

const result = await client.relay.createSafe({
  name: "Production Alerts",
  description: "Routes critical production incidents",
});

if (result.error) {
  console.error("Failed to create relay:", result.error.message);
} else {
  console.log(`Created relay: ${result.data.id}`);
}

curl -X POST https://api.beeps.dev/v0/relay \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Alerts",
    "description": "Routes critical production incidents",
    "externalKey": "prod-alerts"
  }'

Response:

{
  "relay": {
    "id": "rly_abc123",
    "organizationId": "org_xyz789",
    "name": "Production Alerts",
    "description": "Routes critical production incidents",
    "externalKey": "prod-alerts",
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-15T10:30:00Z"
  }
}

Listing Relays

const relays = await client.relay.list();

console.log(`Found ${relays.length} relays:`);
relays.forEach((relay) => {
  console.log(`- ${relay.name} (${relay.id})`);
});

curl -X GET https://api.beeps.dev/v0/relay \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "relays": [
    {
      "id": "rly_abc123",
      "organizationId": "org_xyz789",
      "name": "Production Alerts",
      "description": "Routes critical production incidents",
      "externalKey": "prod-alerts",
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-15T10:30:00Z"
    }
  ]
}

Input Types

CreateRelayInput

type CreateRelayInput = {
  name: string; // Required: Human-readable relay name
  description?: string; // Optional: Relay description
  externalKey?: string; // Optional: Custom identifier for API access
};

Relay

type Relay = {
  id: string; // Unique relay identifier (e.g., "rly_abc123")
  organizationId: string; // Organization this relay belongs to
  name: string; // Relay name
  description: string; // Relay description
  externalKey: string | null; // Custom external identifier
  createdAt: string; // ISO 8601 timestamp
  updatedAt: string; // ISO 8601 timestamp
};

Best Practices

Always set externalKey for idempotent configuration. See Best Practices for details.

Error Handling

The SDK throws errors by default. Use the *Safe methods for error handling without exceptions:

const result = await client.relay.createSafe({
  name: "New Relay",
});

if (result.error) {
  console.error(`Error: ${result.error.message}`);
} else {
  console.log(`Success: ${result.data.id}`);
}

For validation failures, the SDK formats a short human-readable message and also keeps structured field-level issues on error.details:

import { ValidationError } from "@beepsdev/sdk";

try {
  await client.relay.rules.create(relay.id, {
    name: "Notify on-call engineer",
    ruleType: "schedule_notify",
    config: {
      schduleId: "sch_primary", // typo
    },
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error(error.message);
    console.error(error.details?.issues);
  }
}

The message will look like:

Invalid config for relay rule `schedule_notify`

- `config.scheduleId` is required.
- `config.schduleId` Unknown field. Did you mean `scheduleId`?