Skip to main content
This is the official TypeScript/Node.js SDK for the Siren notification platform.

​
Installation

npm install @trysiren/node

​
Basic Usage

import { SirenClient, ProviderCode, RecipientChannel } from '@trysiren/node';

// Initialize using environment variables SIREN_API_KEY (and optional SIREN_ENV)
const client = new SirenClient();

// --- Send a direct message (no template) ---
const directMessageId = await client.message.send({
  recipientValue: '[email protected]',
  channel: RecipientChannel.EMAIL,
  body: 'Your account has been successfully verified. You can now access all features.'
});
console.log('Sent direct message:', directMessageId);

// --- Send a message using a template ---
const templatedMessageId = await client.message.send({
  recipientValue: 'U01UBCD06BB',
  channel: RecipientChannel.SLACK,
  templateName: 'welcome_template',
  templateVariables: { user_name: 'John' }
});
console.log('Sent template message:', templatedMessageId);

// --- Send with a specific provider ---
const providerMessageId = await client.message.send({
  recipientValue: '[email protected]',
  channel: RecipientChannel.EMAIL,
  body: 'Your account has been successfully verified.',
  providerName: 'email-provider',
  providerCode: ProviderCode.EMAIL_SENDGRID
});
console.log('Sent with provider:', providerMessageId);

// --- Send using an awesome template identifier ---
const awesomeMessageId = await client.message.sendAwesomeTemplate({
  recipientValue: 'U01UBCD06BB',
  channel: RecipientChannel.SLACK,
  templateIdentifier: 'awesome-templates/customer-support/escalation_required/official/casual.yaml',
  templateVariables: {
    ticket_id: '123456',
    customer_name: 'John',
    issue_summary: 'Payment processing issue',
    ticket_url: 'https://support.company.com/ticket/123456',
    sender_name: 'Support Team'
  },
  providerName: 'slack-provider',
  providerCode: ProviderCode.SLACK
});
console.log('Sent awesome template:', awesomeMessageId);

​
SDK Methods

The Siren TypeScript SDK provides a clean, namespaced interface to interact with the Siren API. Below are the available methods organized by functionality.

​
Templates

MethodDescription
client.template.get()Retrieves a list of notification templates with optional filtering, sorting, and pagination
client.template.create()Creates a new notification template
client.template.update()Updates an existing notification template
client.template.delete()Deletes an existing notification template
client.template.publish()Publishes a template, making its latest draft version live

​
Channel Templates

MethodDescription
client.template.createChannelTemplate()Creates or updates channel-specific templates (EMAIL, SMS, etc.)
client.template.getChannelTemplates()Retrieves channel templates for a specific template version

​
Messaging

MethodDescription
client.message.send()Sends a message (with or without using a template) to a recipient via a chosen channel
client.message.sendAwesomeTemplate()Sends a message using a template path/identifier
client.message.getReplies()Retrieves replies for a specific message ID
client.message.getStatus()Retrieves the status of a specific message (SENT, DELIVERED, FAILED, etc.)

​
Workflows

MethodDescription
client.workflow.trigger()Triggers a workflow with given data and notification payloads
client.workflow.triggerBulk()Triggers a workflow in bulk for multiple recipients
client.workflow.schedule()Schedules a workflow to run at a future time (once or recurring)

​
Webhooks

MethodDescription
client.webhook.configureNotifications()Configures webhook URL for receiving status updates
client.webhook.configureInbound()Configures webhook URL for receiving inbound messages

​
Users

MethodDescription
client.user.add()Creates a new user or updates existing user with given unique_id
client.user.update()Updates an existing user’s information
client.user.delete()Deletes an existing user

​
For Package Developers

​
Environment Configuration

For testing the SDK, set these environment variables:
  • SIREN_API_KEY: Your API key from the Siren dashboard
  • SIREN_ENV: Set to dev for development/testing (defaults to prod)

​
Prerequisites

  • Git
  • Node.js 14 or higher
  • npm or yarn

​
Setup Steps

1

Clone the repository

git clone https://github.com/KeyValueSoftwareSystems/siren-ts-sdk.git
cd siren-ts-sdk
2

Install dependencies

# Using npm
npm install
  
# Or using yarn
yarn install
3

Set up pre-commit hooks

# Using npm
npm run prepare

# Or using yarn
yarn prepare
You are now ready to contribute to the @trysiren/node SDK!

​
Code Style & Linting

Code style is enforced by:
  • ESLint and Prettier for code formatting
  • TypeScript compiler for type checking
These tools are automatically run via pre-commit hooks.

​
Running Tests

To run the test suite, use the following command from the project root directory: 
# Using npm
npm test

# Or using yarn
yarn test
This will execute all tests defined in the src/__tests__/ directory.

​
Submitting Changes

  1. Create a feature branch for your changes
  2. Commit your changes (pre-commit hooks will run)
  3. Push your branch and open a Pull Request against the develop branch