NTFY Client (Unofficial)

This package was originally created for my personal project, and I decided to publish it in case it helps someone else.

⚠️ Important notes:

• This is not an official NTFY client.
• The project is not actively maintained.
• APIs may change, break, or be incomplete.
• Use it at your own risk.

If you want something stable or feature-complete, you should probably look for an official or community-maintained library instead.

Usage

Installation

npm install @acquachris/ntfy-client

Quick Start

ES Modules

import { NTFYClient, NTFYAuthType, NTFYActionButtonBuilder } from "@acquachris/ntfy-client";

const client = new NTFYClient({
  baseUrl: "https://ntfy.acquachris.it",
  auth: {
    type: NTFYAuthType.Token,
    token: "YOUR_TOKEN_HERE"
  }
});

// Send a simple message
await client.SendMessage("test", {
  message: "test message",
  title: "test title"
});

CommonJS

const { NTFYClient, NTFYAuthType, NTFYActionButtonBuilder } = require("@acquachris/ntfy-client");

const client = new NTFYClient({
  baseUrl: "https://ntfy.acquachris.it",
  auth: {
    type: NTFYAuthType.Token,
    token: "YOUR_TOKEN_HERE"
  }
});

// Send a simple message
await client.SendMessage("test", {
  message: "test message",
  title: "test title"
});

Examples

Basic Message

const client = new NTFYClient({
  baseUrl: "https://ntfy.sh"
});

await client.SendMessage("my-topic", {
  message: "Hello from ntfy!",
  title: "Notification"
});

Authentication

Token Authentication

const client = new NTFYClient({
  baseUrl: "https://ntfy.sh",
  auth: {
    type: NTFYAuthType.Token,
    token: "tk_your_token_here"
  }
});

Basic Authentication

const client = new NTFYClient({
  baseUrl: "https://ntfy.sh",
  auth: {
    type: NTFYAuthType.Basic,
    username: "your_username",
    password: "your_password"
  }
});

Adding Action Buttons

const button = new NTFYActionButtonBuilder()
  .SetType("view")
  .SetUrl("https://example.com/login")
  .SetLabel("Open Login");

await client.SendMessage("test", {
  message: "Click the button below to login",
  title: "Action Required",
  actions: [button]
});

Multiple Actions

const viewButton = new NTFYActionButtonBuilder()
  .SetType("view")
  .SetUrl("https://example.com")
  .SetLabel("View Details");

const httpButton = new NTFYActionButtonBuilder()
  .SetType("http")
  .SetUrl("https://api.example.com/confirm")
  .SetLabel("Confirm");

await client.SendMessage("notifications", {
  message: "Your order has been processed",
  title: "Order Confirmation",
  actions: [viewButton, httpButton]
});

API Reference

NTFYClient

Constructor options:

• baseUrl (optional): The ntfy server URL. Default: "https://ntfy.sh"
• auth (optional): Authentication configuration

NTFYAuthType

Enum values:

• NTFYAuthType.None: No authentication
• NTFYAuthType.Token: Token-based authentication
• NTFYAuthType.Basic: Basic username/password authentication

SendMessage(topic: string, options: MessageOptions)

Send a notification to a specific topic.

Options:

• message: The notification message (required)
• title: The notification title (optional)
• actions: Array of action buttons (optional)

Returns: Promise<void>