VelaManagementClient handles all account-level operations. It authenticates with your client secret (vela_cs_...) and has full access to create apps, define schemas, configure notification rules, and rotate API keys.
Constructor
import { VelaManagementClient } from '@vela-event/sdk';
const client = new VelaManagementClient(process.env.VELA_CLIENT_SECRET!);
| Option | Type | Default | Description |
|---|---|---|---|
baseUrl | string | https://api.velahq.xyz | API base URL. Override for self-hosted instances. |
timeout | number | 30000 | Request timeout in milliseconds. |
fetchImpl | typeof fetch | globalThis.fetch | Custom fetch implementation. |
Apps
List all apps
const apps = await client.apps.list();
for (const app of apps) {
console.log(`${app.name} (${app.slug}) — key hint: ${app.apiKeyHint}`);
// "Order Service (order-service) — key hint: vela_live_abc1..."
}
Create an app
const { app, apiKey } = await client.apps.create({ name: 'Order Service' });
console.log(app.slug); // "order-service"
console.log(apiKey); // "vela_live_..." — shown only once, store immediately
The full API key is only returned at creation time. Store it in your secret manager immediately — Vela only stores a hashed version and cannot recover the original.
Rotate an API key
const { app, apiKey } = await client.apps.rotateKey('order-service');
console.log(apiKey); // new key — update all services using the old key
// The old key is immediately invalid after this call
Delete an app
await client.apps.delete('order-service');
App-scoped resources
Schemas, notification rules, and events are scoped to a specific app. UseforApp() to get resource handles for a particular app:
const app = client.forApp('order-service'); // accepts slug or UUID
app.schemas, app.notificationRules, and app.events operate on that specific app.
Schemas
List schemas
const schemas = await app.schemas.list();
for (const schema of schemas) {
console.log(`${schema.eventName} — ${schema.fields.length} fields`);
}
Get a schema
const schema = await app.schemas.get('order.placed');
console.log(schema.fields);
Create a schema
await app.schemas.create({
eventName: 'order.placed',
description: 'Fired when a customer completes checkout',
fields: [
{ id: 'f1', name: 'orderId', type: 'string', required: true },
{ id: 'f2', name: 'amountCents', type: 'number', required: true },
{ id: 'f3', name: 'currency', type: 'enum', required: true,
enumValues: ['USD', 'EUR', 'GBP'] },
{ id: 'f4', name: 'customerEmail', type: 'string', required: false },
],
metadataFields: [
{ id: 'm1', name: 'environment', type: 'string' },
{ id: 'm2', name: 'traceId', type: 'string' },
],
});
Update a schema
await app.schemas.update('order.placed', {
description: 'Updated description',
fields: [
{ id: 'f1', name: 'orderId', type: 'string', required: true },
{ id: 'f2', name: 'amountCents', type: 'number', required: true },
{ id: 'f3', name: 'currency', type: 'enum', required: true,
enumValues: ['USD', 'EUR', 'GBP', 'CAD'] }, // added CAD
{ id: 'f4', name: 'customerEmail', type: 'string', required: false },
{ id: 'f5', name: 'promoCode', type: 'string', required: false }, // new field
],
});
Delete a schema
await app.schemas.delete('order.placed');
Notification rules
List rules
const rules = await app.notificationRules.list();
Create a rule
await app.notificationRules.create({
name: 'Alert on high-value orders',
eventName: 'order.placed',
conditions: [
{ field: 'amountCents', operator: 'gt', value: 10000 },
{ field: 'currency', operator: 'eq', value: 'USD' },
],
actions: [
{
id: 'action-slack',
destinationId: 'dest-uuid-from-dashboard',
channel: 'slack',
enabled: true,
},
{
id: 'action-email',
destinationId: 'dest-uuid-from-dashboard',
channel: 'email',
enabled: true,
},
],
});
Update a rule
await app.notificationRules.update('rule-uuid', {
name: 'Alert on high-value orders (updated)',
conditions: [
{ field: 'amountCents', operator: 'gt', value: 20000 }, // raised threshold
],
});
Toggle a rule on/off
await app.notificationRules.update('rule-uuid', { enabled: false });
await app.notificationRules.update('rule-uuid', { enabled: true });
Delete a rule
await app.notificationRules.delete('rule-uuid');
Events (read-only)
List events
const events = await app.events.list({
eventName: 'order.placed',
level: 'error',
customerId: 'cust_42',
from: '2024-06-01T00:00:00Z',
to: '2024-06-30T23:59:59Z',
limit: 50,
});
for (const event of events) {
console.log(`${event.id} — ${event.eventName} at ${event.createdAt}`);
}
Get a single event
const event = await app.events.get('evt_01j9abc...');
console.log(event.data); // the payload
console.log(event.metadata); // the metadata
Complete setup example
import { VelaManagementClient } from '@vela-event/sdk';
const client = new VelaManagementClient(process.env.VELA_CLIENT_SECRET!);
// 1. Create the app
const { app, apiKey } = await client.apps.create({ name: 'Payments Service' });
console.log('API key (save this now):', apiKey);
// 2. Define schemas
const svc = client.forApp(app.slug);
await svc.schemas.create({
eventName: 'payment.captured',
fields: [
{ id: 'f1', name: 'paymentId', type: 'string', required: true },
{ id: 'f2', name: 'amountCents', type: 'number', required: true },
{ id: 'f3', name: 'currency', type: 'enum', required: true,
enumValues: ['USD', 'EUR', 'GBP'] },
],
});
await svc.schemas.create({
eventName: 'payment.failed',
fields: [
{ id: 'f1', name: 'paymentId', type: 'string', required: true },
{ id: 'f2', name: 'reason', type: 'enum', required: true,
enumValues: ['card_declined', 'insufficient_funds', 'expired_card'] },
],
});
// 3. Set up alert rule
await svc.notificationRules.create({
name: 'Alert on payment failures',
eventName: 'payment.failed',
conditions: [],
actions: [
{ id: 'a1', destinationId: '<slack-dest-id>', channel: 'slack', enabled: true },
],
});
console.log('Setup complete.');