> ## 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.

# TypeScript SDK

> Official TypeScript/JavaScript SDK for the Vela platform — type-safe event ingestion and account management with zero runtime dependencies.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @vela-event/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @vela-event/sdk
  ```

  ```bash yarn theme={null}
  yarn add @vela-event/sdk
  ```
</CodeGroup>

**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:

| Client                 | Credential                    | Purpose                                      |
| ---------------------- | ----------------------------- | -------------------------------------------- |
| `VelaIngestClient`     | API key (`vela_live_...`)     | Send events into your app                    |
| `VelaManagementClient` | Client 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

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Ingest Client" icon="bolt" href="/sdks/typescript/ingest-client">
    Single and batch event ingestion, event fields, levels.
  </Card>

  <Card title="Management Client" icon="gear" href="/sdks/typescript/management-client">
    Apps, schemas, notification rules — all resource methods.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/sdks/typescript/error-handling">
    Typed exceptions, network errors, retry guidance.
  </Card>

  <Card title="Installation" icon="download" href="/sdks/typescript/installation">
    Setup, credentials, edge runtime support.
  </Card>
</CardGroup>