JavaScript SDK

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

Install

Code

npm install @trigv/sdk

Send a notification

Code

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",
});

Keep it server-side. Never expose your Trigv API key in browser JavaScript.

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.

Code

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.

Code

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

Error handling

Code

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

Additional resources

NPM package Install the official Trigv JavaScript SDK from npm.

Source code View the JavaScript SDK source on GitHub.