onetriggr/README.md

Node.js client library for OneTriggr event triggering

# onetriggr

Official Node.js client library for OneTriggr event triggering platform.

[![npm version](https://badge.fury.io/js/onetriggr.svg)](https://badge.fury.io/js/onetriggr)
[![CI](https://github.com/sourabhbajaj/onetriggr-node-lib/workflows/CI/badge.svg)](https://github.com/sourabhbajaj/onetriggr-node-lib/actions)

## Installation

```bash
npm install onetriggr
```

## Quick Start

First, get your API key by signing up at [www.onetriggr.com](https://www.onetriggr.com).

```javascript
import { OneTriggr } from 'onetriggr';

const client = new OneTriggr({
  apiKey: 'your-api-key-here'
});

// Trigger an event
const response = await client.triggr(
  'user-signup',
  { emailAddress: 'user@example.com' },
  { username: 'john_doe', plan: 'premium' }
);

console.log(response);
```

## Configuration

### Basic Configuration

```javascript
const client = new OneTriggr({
  apiKey: 'your-api-key'
});
```

### Custom Endpoint

```javascript
const client = new OneTriggr({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-custom-endpoint.com'
});
```

### Environment Variables

You can also set the endpoint using an environment variable:

```bash
export ONETRIGGR_ENDPOINT=https://your-custom-endpoint.com
```

The client will use endpoints in this priority order:
1. `baseUrl` from config (if provided)
2. `ONETRIGGR_ENDPOINT` environment variable (if set)
3. Default: `https://api.onetriggr.com`

## API Reference

### `OneTriggr(config)`

Creates a new OneTriggr client instance.

**Parameters:**
- `config.apiKey` (string, required): Your OneTriggr API key (get it from [www.onetriggr.com](https://www.onetriggr.com))
- `config.baseUrl` (string, optional): Custom API endpoint URL

### `client.triggr(eventName, recipient, payload, tenant?)`

Triggers an event in the OneTriggr platform.

**Parameters:**
- `eventName` (string, required): Name of the event to trigger
- `recipient` (object, required): Recipient information
  - `recipient.emailAddress` (string, optional): Email address
  - `recipient.mobileNumber` (string, optional): Mobile number (Indian format: 10 digits starting with 6-9)
- `payload` (object, required): Event parameters as key-value pairs
- `tenant` (string, optional): Tenant identifier for multi-tenant applications

**Returns:** Promise resolving to API response

**Example:**
```javascript
const response = await client.triggr(
  'order-confirmation',
  {
    emailAddress: 'customer@example.com',
    mobileNumber: '9876543210'
  },
  {
    orderId: 'ORD-12345',
    amount: '999.99',
    customerName: 'John Doe'
  }
);
```

**Example with Tenant:**
```javascript
const response = await client.triggr(
  'order-confirmation',
  { emailAddress: 'customer@example.com' },
  { orderId: 'ORD-12345' },
  'acme-corp'  // Tenant identifier
);
```

## Error Handling

```javascript
try {
  const response = await client.triggr(
    'user-login',
    { emailAddress: 'user@example.com' },
    { userId: '12345', sessionId: 'abc123' }
  );
  
  if (response.success) {
    console.log('Event triggered successfully');
  } else {
    console.error('Event failed:', response.message);
    if (response.fieldErrors) {
      console.error('Field errors:', response.fieldErrors);
    }
  }
} catch (error) {
  console.error('Network or unexpected error:', error.message);
}
```

## TypeScript Support

This library is written in TypeScript and provides full type definitions.

```typescript
import { OneTriggr, Recipient, ApiResponse } from 'onetriggr';

const client = new OneTriggr({ apiKey: 'your-api-key' });

const recipient: Recipient = { emailAddress: 'user@example.com' };
const payload = { firstName: 'John' };

const response: ApiResponse = await client.triggr('welcome-email', recipient, payload);
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- Documentation: [OneTriggr Docs](https://docs.onetriggr.com)
- Issues: [GitHub Issues](https://github.com/sourabhbajaj/onetriggr-node-lib/issues)
- Email: support@onetriggr.com