npm package: @nilovonjs/connect
Description: TypeScript SDK for the Nilovon Connect API
Latest version: 0.1.4

# @nilovonjs/connect

Official TypeScript SDK for the Nilovon Connect API.

- Homepage: https://connect.nilovon.com
- API host: https://api.connect.nilovon.com
- Documentation: https://docs.connect.nilovon.com

## Installation

```bash
npm install @nilovonjs/connect
# or
pnpm add @nilovonjs/connect
# or
yarn add @nilovonjs/connect
# or
bun add @nilovonjs/connect
```

## Quick Start

```ts
import { NilovonConnect } from "@nilovonjs/connect";

const client = new NilovonConnect({ apiKey: "nk_..." });
// or simply:
// const client = new NilovonConnect("nk_...");

// Send an email
await client.emails.send({
  to: "user@example.com",
  from: "hello@yourdomain.com",
  subject: "Welcome!",
  html: "<h1>Hello</h1><p>Welcome to our platform.</p>",
});

// Create a campaign
await client.campaigns.create({
  name: "Weekly Newsletter",
  subject: "This week's updates",
  fromEmail: "news@yourdomain.com",
});

// List contacts
const { items } = await client.contacts.list({ limit: 50 });
```

## Configuration

| Option    | Required | Default                            | Description               |
| --------- | -------- | ---------------------------------- | ------------------------- |
| `apiKey`  | Yes      | —                                  | API key from your dashboard |
| `baseUrl` | No       | `https://api.connect.nilovon.com`  | Custom API base URL       |

## Resources

### Emails

```ts
// Send a single email
await client.emails.send({
  to: "user@example.com",
  from: "hello@yourdomain.com",
  subject: "Hello",
  html: "<p>Content here</p>",
  replyTo: "support@yourdomain.com",
  scheduledAt: "2025-01-01T10:00:00Z", // optional
});

// Get a message by ID
const message = await client.emails.get("msg_...");

// List messages
const { items } = await client.emails.list({ limit: 20, status: "sent" });
```

### Contacts

```ts
await client.contacts.create({ email: "user@example.com", name: "Jane Doe", tags: ["vip"] });
await client.contacts.get("contact_id");
await client.contacts.list({ search: "jane", limit: 50 });
await client.contacts.update("contact_id", { name: "Jane Smith" });
await client.contacts.delete("contact_id");
```

### Campaigns

```ts
await client.campaigns.create({ name: "Launch Announcement", subject: "We launched!", fromEmail: "hi@example.com" });
await client.campaigns.update({ id: "camp_id", bodyHtml: "<h1>Hello</h1>" });
await client.campaigns.schedule("camp_id"); // send now
await client.campaigns.schedule("camp_id", "2025-06-01T09:00:00Z"); // schedule
await client.campaigns.pause("camp_id");
await client.campaigns.resume("camp_id");
await client.campaigns.duplicate("camp_id");
await client.campaigns.delete("camp_id");
```

### Domains

```ts
await client.domains.create("mail.yourdomain.com");
await client.domains.list();
await client.domains.verify("domain_id");
await client.domains.delete("domain_id");
```

### Templates

```ts
await client.templates.create({ name: "Welcome", channelType: "email", body: "<p>Hello {{name}}</p>" });
await client.templates.list({ channelType: "email" });
await client.templates.update("tmpl_id", { subject: "Updated subject" });
await client.templates.delete("tmpl_id");
```

### Webhooks

```ts
await client.webhooks.create({ url: "https://yourdomain.com/webhook", events: ["message.sent"] });
await client.webhooks.list();
await client.webhooks.update("wh_id", { isActive: false });
await client.webhooks.delete("wh_id");
```

## Webhook Verification

Verify incoming webhook signatures using HMAC-SHA256:

```ts
import { NilovonConnect } from "@nilovonjs/connect";

const isValid = await NilovonConnect.verifyWebhook(
  "your_webhook_secret",
  requestBody,
  request.headers["x-webhook-signature"],
);

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}
```

## Advanced: Raw Client

For advanced usage, access the underlying oRPC client directly:

```ts
const client = new NilovonConnect("nk_...");

// Use the raw oRPC client
const result = await client.raw.message.send({ ... });
```

## Error Handling

```ts
import { ORPCError } from "@orpc/client";

try {
  await client.contacts.get("nonexistent");
} catch (error) {
  if (error instanceof ORPCError) {
    console.error(error.code, error.message);
  }
}
```

## TypeScript

The SDK is fully typed. Import types as needed:

```ts
import type { SendEmailParams, ContactParams, CreateCampaignParams } from "@nilovonjs/connect";
```