---
title: TypeScript SDK
description: Install @emitkit/js and send events from TypeScript or JavaScript.
sidebar:
  order: 0
---

The `@emitkit/js` package wraps EmitKit's HTTP API for server-side TypeScript
and JavaScript. Keep the API key on the server; never include it in a browser
bundle or public environment variable.

## Install

<CodeGroup>
```bash npm
npm install @emitkit/js
```
```bash pnpm
pnpm add @emitkit/js
```
```bash yarn
yarn add @emitkit/js
```
</CodeGroup>

## Send an event

```typescript
import { EmitKit } from '@emitkit/js';

const client = new EmitKit(process.env.EMITKIT_API_KEY!);

const result = await client.events.create({
  channelName: 'general',
  title: 'Hello from EmitKit',
  description: 'My first event',
});

console.log(result.data.id);
```

The API key selects the Project. `channelName` selects or creates a Channel in
that Project, so the request body doesn't contain an Organization or Project
identifier.

## Add monetary context

`metadata` accepts arbitrary JSON. This makes it useful for monetary context
such as an amount, currency, and plan:

```typescript
const result = await client.events.create({
  channelName: 'payments',
  title: 'Payment Received',
  description: 'User upgraded to Pro plan',
  icon: '💰',
  tags: ['payment', 'upgrade'],
  metadata: {
    amount: 99.99,
    currency: 'USD',
    plan: 'pro',
  },
  userId: 'user_123',
  notify: true,
});
```

:::warning
Metadata describes an event. EmitKit does not transfer, charge, settle, or
otherwise process money.
:::

`notify` defaults to `true`: the event sends a
[push notification](/concepts/notifications) to members who turned
notifications on. Set it to `false` for routine events.

## Safe retries

Supply an idempotency key when the caller may retry the same occurrence:

```typescript
await client.events.create(
  {
    channelName: 'payments',
    title: 'Payment Received',
    metadata: { paymentId: 'pay_123' },
  },
  { idempotencyKey: 'payment-pay_123' },
);
```

An idempotency key is kept for 24 hours per API key. Repeating the request
returns the first response; reusing the key with a different body returns
`409 Conflict`.

**[Event fields](/sdk/events)**

Choose Channels, metadata, tags, and user attribution.

**[Identify users](/sdk/identify)**

Create identities and aliases.

**[Handle errors](/sdk/error-handling)**

Respond to validation failures and rate limits.

**[Generated API reference](/reference)**

Verify the current request and response contracts.