Back to HomeDashboard →

SDK Reference

Complete reference for the Notifs TypeScript SDK.

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!, // Must start with ntf_live_ or ntf_test_
  baseUrl: 'https://notifs.io',        // Optional, defaults to production
})

Webhooks

webhooks.get(webhookId)

Get an existing webhook by ID. Returns a WebhookClient that you can use to send notifications.

Parameters:

  • webhookId (string): The ID of the webhook

Returns: Promise<WebhookClient>

Example:

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

console.log(webhook.id)        // 'webhook_abc123'
console.log(webhook.name)      // 'Payment Notifications'
console.log(webhook.url)       // 'https://notifs.io/api/webhook/webhook_abc123'

webhooks.create(params)

Create a new webhook.

Parameters:

  • params.name (string): Name for the webhook
  • params.projectId (string): Project ID to create the webhook in

Returns: Promise<WebhookClient>

Example:

const webhook = await notifs.webhooks.create({
  name: 'Payment Notifications',
  projectId: 'project_abc123'
})

webhooks.list(projectId?)

List all webhooks, optionally filtered by project.

Parameters:

  • projectId (string, optional): Filter by project ID

Returns: Promise<WebhookClient[]>

Example:

// List all webhooks
const webhooks = await notifs.webhooks.list()

// List webhooks for a specific project
const projectWebhooks = await notifs.webhooks.list('project_abc123')

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

WebhookClient

The WebhookClient is returned by webhooks.get(), webhooks.create(), and webhooks.list(). Use it to send notifications.

Properties

  • id (string): Webhook ID
  • name (string): Webhook name
  • projectId (string): Project ID
  • userId (string): Owner's user ID
  • url (string): Full webhook URL

webhook.send(params)

Send a notification through this webhook to all configured channels.

Parameters:

  • params.title (string): Notification title
  • params.message (string, optional): Notification body
  • params.data (object, optional): Additional structured data
  • params.[key] (any): Any other custom fields

Returns: Promise<NotificationResponse>

Example:

const response = await webhook.send({
  title: 'New Order Received',
  message: 'Order #1234 has been placed',
  orderId: '1234',
  amount: 99.99,
  customer: 'john@example.com'
})

console.log(response.notificationId)   // 'notif_xyz789'
console.log(response.servicesExecuted) // true

Response

interface NotificationResponse {
  message: string
  notificationId: string
  servicesExecuted: boolean
  usageInfo?: {
    current: number
    limit: number
    inGracePeriod?: boolean
  }
}

Error Handling

All SDK methods can throw NotifsError:

import { Notifs, NotifsError } from '@notifs/sdk'

try {
  await webhook.send({ title: 'Hello' })
} catch (error) {
  if (error instanceof NotifsError) {
    console.error('Message:', error.message)
    console.error('Status:', error.status)   // HTTP status code
    console.error('Code:', error.code)       // Error code (e.g., 'rate_limit_exceeded')
  }
}

Common Error Codes

| Code | Status | Description | |------|--------|-------------| | unauthorized | 401 | Invalid or missing API key | | not_found | 404 | Webhook not found | | rate_limit_exceeded | 429 | Rate limit exceeded | | replay_attack_detected | 409 | Duplicate request within 5 minutes | | quota_exceeded | 402 | Usage limit exceeded |

TypeScript Support

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

import {
  Notifs,
  NotifsError,
  NotificationResponse
} from '@notifs/sdk'

const response: NotificationResponse = await webhook.send({
  title: 'Payment Received',
  amount: 99.99
})

Full Example

import { Notifs, NotifsError } from '@notifs/sdk'

const notifs = new Notifs({
  apiKey: process.env.NOTIFS_API_KEY!
})

async function sendPaymentNotification(orderId: string, amount: number) {
  try {
    // Get your webhook
    const webhook = await notifs.webhooks.get('webhook_abc123')

    // Send notification
    const response = await webhook.send({
      title: 'Payment Received',
      message: `Order ${orderId} - $${amount}`,
      orderId,
      amount,
      timestamp: new Date().toISOString()
    })

    console.log('Notification sent:', response.notificationId)
    return response
  } catch (error) {
    if (error instanceof NotifsError) {
      console.error(`Failed to send notification: ${error.message}`)
    }
    throw error
  }
}

Next Steps