Skip to main content

​
Installation

npm install @vela-event/sdk

pnpm add @vela-event/sdk

yarn add @vela-event/sdk
Requirements: Node.js 18+ (uses native fetch). Also works in modern browsers, Cloudflare Workers, Vercel Edge, and Deno.

​
Two clients, two credentials

The SDK exports two separate clients, each scoped to a different credential and purpose:
ClientCredentialPurpose
VelaIngestClientAPI key (vela_live_...)Send events into your app
VelaManagementClientClient secret (vela_cs_...)Create apps, manage schemas, configure rules
The separation is intentional. Your API key lives in your production services and travels with every event. Keeping it separate from your client secret means a leaked API key can only ingest events — it can’t read your data, modify schemas, or touch other apps.

​
Quick example

import { VelaIngestClient, VelaManagementClient } from '@vela-event/sdk';

// --- Ingestion (runs in your production service) ---
const ingest = new VelaIngestClient(process.env.VELA_API_KEY!);

const result = await ingest.ingest({
  event: 'order.placed',
  data: { orderId: 'ord_abc123', amountCents: 4999, currency: 'USD' },
  level: 'info',
  customer_id: 'cust_42',
});

console.log(result.accepted);      // 1
console.log(result.events[0].id);  // "evt_01j9..."

// --- Management (runs in scripts, CI, or your backend setup) ---
const client = new VelaManagementClient(process.env.VELA_CLIENT_SECRET!);

// List all apps
const apps = await client.apps.list();

// Work with a specific app
const app = client.forApp('order-service');

// Create a schema
await app.schemas.create({
  eventName: 'order.placed',
  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'] },
  ],
});

​
Features

  • Zero dependencies — uses native fetch, no extra packages to audit
  • Dual CJS + ESM — works with require() and import equally
  • Full TypeScript types — all inputs and responses are typed; no any leakage
  • Typed error hierarchy — catch VelaNotFoundError, VelaValidationError, etc. specifically
  • Batch ingestion — send up to 100 events in one request

​
Next steps

Ingest Client

Single and batch event ingestion, event fields, levels.

Management Client

Apps, schemas, notification rules — all resource methods.

Error Handling

Typed exceptions, network errors, retry guidance.

Installation

Setup, credentials, edge runtime support.