---
title: JavaScript SDK
description: Install and use the official Trigv TypeScript SDK for Node.js, serverless functions, scripts, and CI jobs.
---
# JavaScript SDK

Use the official Trigv TypeScript SDK to send push notifications from Node.js, serverless functions, backend scripts, and CI jobs.

## Install

```
npm install @trigv/sdk
```

## Send a notification

```
import { Trigv } from "@trigv/sdk";

const trigv = new Trigv({
		apiKey: process.env.TRIGV_API_KEY,
});

const { event, duplicate } = await trigv.sendEvent({
		channel: "general",
		title: "Deploy finished",
		description: "Production is live",
		level: "success",
		event_type: "deploy.completed",
});
```

<div>
  <strong>Keep it server-side.</strong>
  Never expose your Trigv API key in browser JavaScript.
</div>

## Event fields

| Field | Required | Description |
| --- | :---: | --- |
| `channel` | Yes | Channel slug, such as `general`, `deploys`, or `payments`. |
| `title` | Yes | Push notification title. |
| `description` | No | Body text shown in the notification. |
| `image_url` | No | HTTPS image URL for screenshots, charts, camera snapshots, or previews. |
| `url` | No | Destination URL opened from the notification. |
| `level` | No | `info`, `success`, `warning`, or `error`. Defaults to `info`. |
| `delivery_urgency` | No | `standard` or `time_sensitive`. Defaults to `standard`. |
| `event_type` | No | Free-form event label such as `deploy.completed` or `cron.failed`. |
| `idempotency_key` | No | Deduplication key for safe retries. |

## Levels and urgency

Use `level` for meaning, not styling. `success` is for completed work, `warning` is for attention soon, and `error` is for failures that need action.

Use `delivery_urgency: "time_sensitive"` only for alerts that should break through normal notification delivery rules.

## Safe retries with idempotency

Set `idempotency_key` when a job or CI step may retry the same event.

```
await trigv.sendEvent({
		channel: "deploys",
		title: "Production deploy complete",
		level: "success",
		idempotency_key: "deploy-prod-42",
});
```

Retries with the same key return the existing event with `duplicate: true` instead of billing and sending another alert.

## Configuration

| Option | Default | Description |
| --- | --- | --- |
| `apiKey` | `TRIGV_API_KEY` | Workspace API key. |
| `baseUrl` | `https://api.trigv.com/api` | API base URL. |
| `timeout` | `30000` | Request timeout in milliseconds. |
| `maxRetries` | `2` | Retry count for retryable failures. |

## Verify the API key

Use `verifyConnection()` to check credentials without sending a notification.

```
const connection = await trigv.verifyConnection();
console.log(connection.workspace.name);
```

## Error handling

```
import {
		AuthenticationError,
		NotFoundError,
		RateLimitError,
		ValidationError,
} from "@trigv/sdk";

try {
		await trigv.sendEvent({ channel: "general", title: "Hello" });
} catch (error) {
		if (error instanceof ValidationError) {
			console.error(error.errors);
		} else if (error instanceof NotFoundError) {
			console.error("Channel not found");
		} else if (error instanceof RateLimitError) {
			console.error(error.retryable ? "Retry later" : "Monthly limit reached");
		} else if (error instanceof AuthenticationError) {
			console.error("Invalid API key");
		}
}
```

## Good places to use it

- Server-side route handlers after payment, form, or webhook events
- CI/CD steps that should alert your phone when a workflow finishes
- Cron jobs, background jobs, and scripts where a push alert is easier than checking logs

<DocsResourceLinks
  packageHref="https://www.npmjs.com/package/@trigv/sdk"
  packageTitle="NPM package"
  packageDescription="Install the official Trigv JavaScript SDK from npm."
  packageLabel="npm"
  sourceHref="https://github.com/Trigv/trigv-node"
  sourceDescription="View the JavaScript SDK source on GitHub."
/>