> ## 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.

# TypeScript

This is the official TypeScript/Node.js SDK for the Siren notification platform.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @trysiren/node
  ```

  ```bash Yarn theme={null}
  yarn add @trysiren/node
  ```
</CodeGroup>

## Basic Usage

```typescript theme={null}
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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/KeyValueSoftwareSystems/siren-ts-sdk.git
    cd siren-ts-sdk
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    # Using npm
    npm install
      
    # Or using yarn
    yarn install
    ```
  </Step>

  <Step title="Set up pre-commit hooks">
    ```bash theme={null}
    # Using npm
    npm run prepare

    # Or using yarn
    yarn prepare
    ```
  </Step>
</Steps>

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:

```bash theme={null}
# 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