sensecap-notification-proxy v1.0.2

Notification Service

This service allows you to send notifications to various channels (Discord, HomeAssistant, IFTTT, Webhook, etc.) based on configurable parameters. It provides a unified API to configure notification channels, send notifications, and handle server setup.

Features

• Support for multiple notification providers: Discord, HomeAssistant, IFTTT, Webhook.
• Configurable server with various modes (Remote, Local, Tool).
• Supports customizable notification payloads, including sensor data.
• Simple and extendable architecture for adding new notification providers.

Table of Contents

1. Installation
2. Usage
3. Configuration
4. API Reference
5. Provider Details
6. License

Installation

(Recommend) Install with npm.

npm install sensecap-notification-proxy

Or clone the repository and install the dependencies.

git clone https://github.com/Seeed-Studio/SenseCAP-Notification-Proxy
cd notification-service
npm install

Usage

1 Tool Mode (Recommend)

• use as Tool, easily combine with your code
• Both JavaScript and TypeScript are supported

Example in TS:

import { sendNotification } from 'sensecap-notification-proxy';
(async () => {
  await sendNotification(
    {
      requestId: '01daeb5a-xxx-xxx-xxx-c45a23040062',
      deviceEui: 'xxxF1C86220006A',
      events: {
        timestamp: 1722333017264,
        text: 'people detected',
        img: '',
        data: {
          sensor: {
            temperature: 29.2,
            humidity: 58,
            CO2: 699,
          },
        },
      },
    },
    {
      configs: {
        type: 'Discord',
        discordWebhookUrl:
          'https://discord.com/api/webhooks/.../...',
      },
    }
  );
})();

2 Local Mode

• it will save data in node_modules/sensecap-notification-proxy/
• so best option is used as Tool

Example in JS:

const { createServer } = require('sensecap-notification-proxy');
createServer({ verbose: true, SVC_TYPE: 0 });

3 Server Mode

• run without create token, but need to be customize your auth way
• so best option is used as Tool

Example in TS:

import { createServer, ServerConfig } from 'sensecap-notification-proxy';

// Example configuration
const config: ServerConfig = {
  authTokenFilePath: '/path/to/token/file',
  configFilePath: '/path/to/config/file',
  port: 3000,
  hostname: 'localhost',
  SVC_TYPE: 0, // Local mode
  verbose: true,
};

// Create and start the server
const server = createServer(config);

Configuration

The server and notification system are configurable through the following parameters:

ServerConfig

• authTokenFilePath (string): Path to the file containing the authentication token.
• configFilePath (string): Path to the channel configuration file.
• port (number): The port on which the server will run.
• hostname (string): The hostname for the server.
• SVC_TYPE (number): Defines the service type:
  • 1 = Remote mode
  • 0 = Local mode
  • 2 = Tool mode
• verbose (boolean): Whether to log additional details for debugging.

NotificationConfig

• requestId (string): The unique request ID for the notification.
• deviceEui (string): The device identifier.
• events (object): Contains the details of the event:
  • timestamp (number): The timestamp of the event.
  • text (string): The event's textual message.
  • img (string): A URL to the event's image.
  • data (object): Sensor data (e.g., temperature, humidity, CO2 levels).

ProviderConfig

• type (string, optional): The type of notification provider (e.g., Discord, HomeAssistant, IFTTT, WebHook).
• configs (object): Configuration specific to the selected provider:
  • discordWebhookUrl (string, for Discord)
  • discordUsername (string, for Discord)
  • webhookURL (string, for WebHook and IFTTT)
  • headers (string, for WebHook and IFTTT)
  • host, port, username, password, topic (string, for HomeAssistant and MQTT-based integrations)
  • webhookContentType (string, for WebHook)
  • webhookCustomBody (string, for WebHook)

API Reference

createServer(config: ServerConfig): Express

Creates and configures the notification server.

• config: The configuration object with settings for the server.
• Returns an Express app instance.

sendNotification(notification: NotificationConfig, config: ProviderConfig, verbose?: boolean): Promise<SendResponse>

Sends a notification to the specified provider.

• notification: The notification details, including event data.
• config: The provider configuration (Discord, HomeAssistant, etc.).
• verbose: Optional flag to enable logging.
• Returns a SendResponse object containing the result.

SendResponse

Response object returned from sendNotification:

• code: The status code (e.g., 200 for success).
• msg: The message describing the result.
• data: Optional additional data.

Provider Details

1. Discord

To send notifications via Discord, you need the webhook URL and optional settings like the username and avatar.

2. HomeAssistant

HomeAssistant requires an MQTT broker configuration (host, port, username, password) and a topic to send the message to.

3. IFTTT

IFTTT uses a webhook URL for sending notifications. Optionally, additional headers can be provided.

4. Webhook

A generic webhook provider that allows you to send data to a specified URL.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Note: The above README assumes the project implements notification sending through different services (Discord, HomeAssistant, IFTTT, etc.). You can adjust and expand the documentation as necessary based on the actual implementation details in sensecap project.