npm package: @notiflow/node
Description: Official Node.js/TypeScript SDK for Notiflow - Event-driven notification platform
Author: Notiflow
Latest version: 1.0.0

# Notiflow Node.js SDK

Official Node.js/TypeScript SDK for [Notiflow](https://notiflow.io) - Event-driven notification platform.

## Installation

```bash
npm install @notiflow/node
# or
yarn add @notiflow/node
# or
pnpm add @notiflow/node
```

## Quick Start

```typescript
import { Notiflow } from '@notiflow/node';

const notiflow = new Notiflow('sk_live_...');

// Trigger an event
const result = await notiflow.trigger('order.completed', {
  user_id: 'user_123',
  email: 'john@example.com',
  order_id: 'ORD-456',
  total: 99.99,
  currency: 'USD',
});

if (result.isSuccess()) {
  console.log('Event sent! ID:', result.eventId);
} else {
  console.log('Failed:', result.error);
}
```

## Features

- **Error-safe**: Never throws exceptions - all errors are captured in the Result object
- **Zero dependencies**: Uses native fetch (Node 18+)
- **TypeScript-first**: Full type definitions included
- **ESM & CommonJS**: Works with both module systems

## Usage

### Basic Event

```typescript
await notiflow.trigger('user.signup', { plan: 'pro' });
```

### Event with User ID

```typescript
await notiflow.trigger('subscription.renewed', {
  plan: 'enterprise',
  amount: 199.00,
}, { userId: 'user_789' });
```

### Fire-and-Forget (Async)

When you don't need the response:

```typescript
notiflow.triggerAsync('page.viewed', { url: '/pricing' });
```

### Alternative Method Names

```typescript
// These are equivalent:
await notiflow.trigger('order.paid', data);
await notiflow.event('order.paid', data);
await notiflow.track('order.paid', data);
```

### Error Handling

The SDK never throws exceptions. Check the result:

```typescript
const result = await notiflow.trigger('order.paid', data);

if (result.isFailure()) {
  // Log the error, but your app continues running
  console.error('Notiflow error:', result.error);
}
```

## Configuration

### Simple (API key only)

```typescript
const notiflow = new Notiflow('sk_live_...');
```

### Full configuration

```typescript
const notiflow = new Notiflow({
  apiKey: 'sk_live_...',
  baseUrl: 'https://your-instance.notiflow.io', // optional
  timeout: 10000, // optional, in milliseconds
});
```

## Express.js Example

```typescript
import express from 'express';
import { Notiflow } from '@notiflow/node';

const app = express();
const notiflow = new Notiflow(process.env.NOTIFLOW_API_KEY!);

app.post('/orders', async (req, res) => {
  const order = await createOrder(req.body);

  // Fire and forget - don't wait for Notiflow
  notiflow.triggerAsync('order.created', {
    order_id: order.id,
    total: order.total,
  }, { userId: req.user.id });

  res.json(order);
});
```

## Next.js Example

```typescript
// lib/notiflow.ts
import { Notiflow } from '@notiflow/node';

export const notiflow = new Notiflow(process.env.NOTIFLOW_API_KEY!);

// app/api/orders/route.ts
import { notiflow } from '@/lib/notiflow';

export async function POST(request: Request) {
  const data = await request.json();
  const order = await createOrder(data);

  notiflow.triggerAsync('order.created', {
    order_id: order.id,
    total: order.total,
  });

  return Response.json(order);
}
```

## License

MIT