Back to HomeDashboard →

SDK Reference

Complete reference for the Notifs TypeScript SDK. All methods are fully typed and include JSDoc documentation for the best developer experience.

Installation

npm install @notifs/sdk
# or
yarn add @notifs/sdk
# or
pnpm add @notifs/sdk

Initialization

import { Notifs } from '@notifs/sdk'

const notifs = new Notifs({
  apiKey: process.env.NOTIFS_API_KEY,
  baseUrl: 'https://api.notifs.dev', // Optional, defaults to production
  timeout: 30000, // Optional, request timeout in ms (default: 30000)
})

Webhooks

webhooks.send(webhookId, data, options?)

Send a notification via webhook. The notification will be delivered to all configured channels.

Parameters:

  • webhookId (string): The ID of the webhook to send
  • data (object): The payload to send with the webhook
  • options (object, optional): Additional options
    • idempotencyKey (string): Unique key to prevent duplicate sends
    • metadata (object): Additional metadata to attach to the request

Returns: Promise<WebhookResponse>

Example:

const response = await notifs.webhooks.send('webhook_abc123', {
  user: 'john@example.com',
  event: 'payment_success',
  amount: '$99.00',
  invoiceUrl: 'https://yourapp.com/invoices/123'
}, {
  idempotencyKey: 'payment_123',
  metadata: { userId: 'user_456' }
})

console.log(response.id) // Request ID for tracking
console.log(response.status) // 'queued' | 'sent' | 'failed'

webhooks.get(webhookId)

Retrieve webhook configuration and details.

Parameters:

  • webhookId (string): The ID of the webhook to retrieve

Returns: Promise<Webhook>

Example:

const webhook = await notifs.webhooks.get('webhook_abc123')

console.log(webhook.name)
console.log(webhook.channels) // ['email', 'slack', 'sms']
console.log(webhook.isActive)

webhooks.list(options?)

List all webhooks for your account.

Parameters:

  • options (object, optional):
    • limit (number): Number of webhooks to return (default: 100)
    • offset (number): Offset for pagination
    • active (boolean): Filter by active status

Returns: Promise<WebhookList>

Example:

const { data, hasMore, total } = await notifs.webhooks.list({
  limit: 50,
  active: true
})

for (const webhook of data) {
  console.log(webhook.name, webhook.id)
}

webhooks.update(webhookId, updates)

Update webhook configuration.

Parameters:

  • webhookId (string): The ID of the webhook to update
  • updates (object): Fields to update

Returns: Promise<Webhook>

Example:

const webhook = await notifs.webhooks.update('webhook_abc123', {
  name: 'Payment Success - Updated',
  isActive: false
})

webhooks.delete(webhookId)

Delete a webhook. This action cannot be undone.

Parameters:

  • webhookId (string): The ID of the webhook to delete

Returns: Promise<void>

Example:

await notifs.webhooks.delete('webhook_abc123')

Logs

logs.list(options?)

Retrieve request logs for debugging and monitoring.

Parameters:

  • options (object, optional):
    • limit (number): Number of logs to return (default: 100)
    • offset (number): Offset for pagination
    • webhookId (string): Filter by webhook ID
    • status (string): Filter by status ('sent', 'failed', etc.)
    • startDate (Date): Filter logs after this date
    • endDate (Date): Filter logs before this date

Returns: Promise<LogList>

Example:

const logs = await notifs.logs.list({
  webhookId: 'webhook_abc123',
  status: 'failed',
  limit: 10
})

for (const log of logs.data) {
  console.log(log.timestamp, log.error)
}

logs.get(logId)

Get detailed information about a specific log entry.

Parameters:

  • logId (string): The ID of the log to retrieve

Returns: Promise<Log>

Example:

const log = await notifs.logs.get('log_xyz789')

console.log(log.webhookId)
console.log(log.payload)
console.log(log.response)
console.log(log.duration) // Request duration in ms

Channels

channels.list()

List all available notification channels.

Returns: Promise<Channel[]>

Example:

const channels = await notifs.channels.list()

for (const channel of channels) {
  console.log(channel.name) // 'Email', 'Slack', 'SMS', etc.
  console.log(channel.isConfigured)
}

channels.configure(channelId, config)

Configure a notification channel.

Parameters:

  • channelId (string): The ID of the channel to configure
  • config (object): Channel-specific configuration

Returns: Promise<Channel>

Example:

// Configure Email channel
await notifs.channels.configure('email', {
  provider: 'mailgun',
  apiKey: process.env.MAILGUN_API_KEY,
  domain: 'mail.yourapp.com',
  fromEmail: 'notifications@yourapp.com',
  fromName: 'Your App'
})

// Configure Slack channel
await notifs.channels.configure('slack', {
  webhookUrl: process.env.SLACK_WEBHOOK_URL,
  channel: '#notifications',
  username: 'Notifs Bot'
})

Error Handling

All SDK methods can throw errors. Use try-catch blocks to handle them:

try {
  await notifs.webhooks.send('webhook_id', data)
} catch (error) {
  if (error instanceof NotifsError) {
    console.error('Notifs error:', error.message)
    console.error('Status code:', error.statusCode)
    console.error('Error code:', error.code)
  } else {
    console.error('Unexpected error:', error)
  }
}

Error Types

  • NotifsError: Base error class for all Notifs errors
  • AuthenticationError: Invalid or missing API key
  • RateLimitError: Rate limit exceeded
  • ValidationError: Invalid request parameters
  • NotFoundError: Resource not found
  • ServerError: Internal server error

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import { Notifs, WebhookResponse, Webhook } from '@notifs/sdk'

// All types are exported and fully documented
const response: WebhookResponse = await notifs.webhooks.send(...)
const webhook: Webhook = await notifs.webhooks.get(...)

Next Steps