Documentation Index
Fetch the complete documentation index at: https://docs.trysiren.io/llms.txt
Use this file to discover all available pages before exploring further.
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: 'alice@company.com',
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: 'alice@company.com',
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
| Method | Description |
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
| Method | Description |
client.template.createChannelTemplate() | Creates or updates channel-specific templates (EMAIL, SMS, etc.) |
client.template.getChannelTemplates() | Retrieves channel templates for a specific template version |
Messaging
| Method | Description |
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
| Method | Description |
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
| Method | Description |
client.webhook.configureNotifications() | Configures webhook URL for receiving status updates |
client.webhook.configureInbound() | Configures webhook URL for receiving inbound messages |
Users
| Method | Description |
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
Clone the repository
git clone https://github.com/KeyValueSoftwareSystems/siren-ts-sdk.git
cd siren-ts-sdk
Install dependencies
# Using npm
npm install
# Or using yarn
yarn install
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
- Create a feature branch for your changes
- Commit your changes (pre-commit hooks will run)
- Push your branch and open a Pull Request against the
develop branch