Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.velahq.xyz/docs/llms.txt

Use this file to discover all available pages before exploring further.

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!);
OptionTypeDefaultDescription
baseUrlstringhttps://api.velahq.xyzAPI base URL. Override for self-hosted instances.
timeoutnumber30000Request timeout in milliseconds.
fetchImpltypeof fetchglobalThis.fetchCustom 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. Use forApp() to get resource handles for a particular app: 
const app = client.forApp('order-service'); // accepts slug or UUID
All methods on 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.');