Signal SDK - TypeScript SDK for Signal Messenger

Features

Core Capabilities

• JSON-RPC Communication - Direct communication with signal-cli daemon
• TypeScript Support - Complete type definitions with IntelliSense
• Message Management - Send, receive, and manage Signal messages
• Real-time Events - Event-driven architecture for incoming messages
• Enterprise-Grade - Robust error handling and retry logic
• Type-Safe Validation - Comprehensive input validation
• Retry Mechanism - Exponential backoff with configurable policies
• Structured Logging - Multi-level logging system
• Configuration Management - Centralized configuration with validation

SignalBot Framework

• Simple Bot Creation - Create powerful bots with minimal setup
• Command System - Built-in command parsing and routing
• Event Handling - React to messages, group events, and user actions
• Admin Controls - Role-based permissions and access control
• Group Management - Automated group creation and member management
• Extensible - Plugin-style architecture for custom functionality

Advanced Features

• Multi-Account Support - Manage multiple Signal accounts simultaneously with MultiAccountManager
• Advanced Messaging - Text styles (bold, italic), mentions, quotes, URL previews, message editing
• Enhanced Receive - Modern receive() method with options (timeout, ignore filters)
• Username Management - Set and delete Signal usernames
• Identity Verification - Get and verify safety numbers, manage untrusted identities
• Advanced Groups - Send invite links, manage banned members, reset group links
• Enhanced Parsing - Extract givenName, familyName, mobileCoinAddress from profiles and contacts
• Daemon Modes - Support for Unix socket, TCP, and HTTP daemon connections
• File Attachments - Send and receive files, images, and media
• Group Operations - Create and manage groups with detailed information
• Contact Management - Manage contacts with export/import capabilities
• Message Reactions - React to messages with emoji
• Typing Indicators - Send and receive typing notifications
• Read Receipts - Track message delivery and read status
• Profile Management - Update profile information and avatars
• Payment Notifications - Send MobileCoin payment notifications with receipts
• Sticker Packs - Upload and manage custom sticker packs
• User Status - Verify Signal registration status
• Rate Limiting - Handle and recover from rate limits
• Phone Number Changes - Change registered phone numbers with verification
• Progress Tracking - Monitor upload progress
• Polls - Create, vote, and terminate polls
• Attachment Retrieval - Retrieve attachments, avatars, and stickers
• Account Management - Update account settings, PIN, and registration
• Note to Self - Send private notes to your own account
• Stories - View and interact with Signal stories
• Group Information - Retrieve detailed group permissions

Quick Start

Installation

npm install signal-sdk

Prerequisites

1. Node.js (version 18 or later)
2. Java Runtime Environment (required by signal-cli)

Note: signal-cli binaries are included with the SDK - no separate installation required.

Detailed installation guide

CLI Commands

The SDK includes a command-line interface for common operations:

# View all available commands
npx signal-sdk --help

# Link a new device to your Signal account
npx signal-sdk connect

# Link with a custom device name
npx signal-sdk connect "My Custom Device Name"

Device Linking

Before using the SDK, you need to link a device to your Signal account:

# Using npx (recommended)
npx signal-sdk connect

# Or with a custom device name
npx signal-sdk connect "My Bot Device"

# Get help for the CLI
npx signal-sdk --help

This command will:

1. Generate a QR code in your terminal
2. Display instructions for scanning with your Signal app
3. Complete the device linking process

Note: You only need to do this once per device. After linking, your device will be permanently connected to your Signal account.

Basic Usage

const { SignalCli } = require("signal-sdk");

// Initialize SignalCli with phone number
const signal = new SignalCli("+33111111111");

// Connect to signal-cli daemon
await signal.connect();

// Send a message
await signal.sendMessage("+33222222222", "Hello from Signal SDK!");

// Listen for incoming messages
signal.on("message", (message) => {
  console.log("Received message:", message.envelope.dataMessage.message);
});

// Graceful shutdown
await signal.gracefulShutdown();

Advanced Configuration

const { SignalCli, Logger } = require("signal-sdk");

// Configure with advanced settings
const config = {
  retryConfig: {
    maxAttempts: 3,
    initialDelay: 1000,
    maxDelay: 10000,
    backoffMultiplier: 2,
  },
  rateLimiter: {
    maxConcurrent: 5,
    minInterval: 200,
  },
  logger: new Logger("info"),
};

const signal = new SignalCli("+33111111111", undefined, config);

await signal.connect();

// SDK automatically retries on failures, respects rate limits,
// validates inputs, and logs operations
await signal.sendMessage("+33222222222", "Reliable messaging!");

Create a Bot

const { SignalBot } = require("signal-sdk");

// Initialize bot with configuration
const bot = new SignalBot({
  phoneNumber: "+33111111111",
  admins: ["+33222222222"],
  group: {
    name: "My Bot Group",
    description: "A group managed by my bot",
    createIfNotExists: true,
  },
});

// Add custom commands
bot.addCommand({
  name: "hello",
  description: "Greet the user",
  handler: async (message, args) => {
    const name = args.join(" ") || "friend";
    return `Hello ${name}! How can I help you today?`;
  },
});

// Handle events
bot.on("ready", () => {
  console.log("Bot is ready and listening for messages!");
});

bot.on("message", (message) => {
  console.log(`Received: ${message.text} from ${message.source}`);
});

// Start the bot
await bot.start();

Your bot will automatically:

• Handle command parsing (default prefix: /)
• Provide built-in commands (/help, /ping)
• Manage group creation and membership
• Enforce admin permissions
• Handle errors gracefully

Documentation

Getting Started

• Installation & Setup
• Getting Started Guide
• Device Linking

API Reference

• SignalCli Class
• SignalBot Class
• TypeScript Interfaces

Examples

• Device Linking - Link your device to Signal
• Basic SDK Usage - Simple message sending
• Quick Start - Complete getting started example
• Group Management - Create and manage groups
• Contact Management - Handle contacts
• File Handling - Send and receive files
• Minimal Bot - Simple bot implementation
• Advanced Bot - Full-featured bot example

Advanced Topics

• Advanced Features
• SignalBot Framework
• Feature Coverage Analysis
• Implementation Plan
• FAQ
• Troubleshooting

Common Use Cases

Send Messages

const { SignalCli } = require("signal-sdk");
const signal = new SignalCli("+33111111111");

await signal.connect();
await signal.sendMessage("+33222222222", "Hello World!");
await signal.gracefulShutdown();

Send Files

// Send file with message
await signal.sendMessage("+33222222222", "Here's the document:", {
  attachments: ["./path/to/document.pdf"],
});

// Send multiple files
await signal.sendMessage("+33222222222", "Photos from today:", {
  attachments: ["./photo1.jpg", "./photo2.jpg"],
});

Group Management

// Create a new group
const group = await signal.createGroup("My Group", [
  "+33222222222",
  "+33333333333",
]);
console.log("Group ID:", group.groupId);

// Send message to group
await signal.sendMessage(group.groupId, "Welcome to the group!");

// Update group info
await signal.updateGroup(group.groupId, {
  title: "Updated Group Name",
  description: "This is our group chat",
});

Bot with Custom Commands

const { SignalBot } = require("signal-sdk");

const bot = new SignalBot({
  phoneNumber: "+33111111111",
  admins: ["+33222222222"],
});

// Add weather command
bot.addCommand({
  name: "weather",
  description: "Get weather information",
  handler: async (message, args) => {
    const city = args.join(" ") || "New York";
    // Integrate with weather API
    return `Weather in ${city}: 22°C, sunny`;
  },
});

// Add custom event handler
bot.on("groupMemberJoined", async (event) => {
  await bot.sendMessage(event.groupId, `Welcome ${event.member.name}!`);
});

await bot.start();

Quality & Reliability

Code Quality

• TypeScript Strict Mode - Full type safety with strict compilation
• Complete Type Coverage - Type definitions for all APIs
• Input Validation - Comprehensive validation throughout
• Error Handling - Robust error classes and management
• Retry Logic - Exponential backoff with configurable policies
• Configuration Management - Validated configuration system

Enterprise Features

• Automatic Retries - Configurable retry policies with exponential backoff
• Rate Limiting - Built-in rate limiter to prevent throttling
• Structured Logging - Multi-level logging system
• Input Sanitization - Automatic sanitization of inputs
• E.164 Validation - Strict international phone number validation
• Connection Management - Graceful connection handling

Technical Specifications

• Node.js: >=18.0.0
• TypeScript: 5.8+ with strict mode
• Test Coverage: 393 passing tests across 21 suites
• Code Coverage: 83.54% overall, critical modules at 96-100%
• signal-cli: Compatible with v0.13.23

Testing

The SDK has comprehensive test coverage to ensure reliability and quality.

Test Statistics

• Total Tests: 393 passing
• Test Suites: 21 suites
• Overall Coverage: 83.54%

Coverage by Module

| Module | Statements | Branches | Functions | Lines | Status | | ----------------- | ---------- | -------- | --------- | ------ | -------------- | | validators.ts | 100% | 100% | 100% | 100% | ✅ Perfect | | config.ts | 100% | 97.22% | 100% | 100% | ✅ Excellent | | errors.ts | 100% | 100% | 100% | 100% | ✅ Perfect | | retry.ts | 96.15% | 85.71% | 100% | 97.95% | ✅ Excellent | | SignalCli.ts | 68.68% | 55.46% | 65.9% | 72.7% | ✅ Good | | SignalBot.ts | 24.33% | 16.94% | 29.68% | 24.59% | ⚠️ In Progress |

Running Tests

# Run all tests
npm test

# Run specific test suite
npm test -- --testNamePattern="SignalCli"

# Run with coverage report
npm run test:coverage

# Run tests in watch mode
npm test -- --watch

Test Suites

1. validators.test.ts - Input validation (100% coverage)
2. config.test.ts - Configuration management (100% coverage)
3. errors.test.ts - Error handling (100% coverage)
4. retry.test.ts - Retry logic (96% coverage)
5. SignalCli.test.ts - Core CLI functionality
6. SignalCli.integration.test.ts - Integration scenarios
7. SignalCli.methods.test.ts - API methods (31 tests)
8. SignalBot.test.ts - Bot framework
9. SignalBot.additional.test.ts - Extended bot features

## Development

```bash
# Clone the repository
git clone https://github.com/your-username/signal-cli-sdk.git
cd signal-cli-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run examples
npm run build && node examples/sdk/01-basic-usage.js

# Run tests
npm test

Configuration

Environment Variables

Create a .env file in your project root:

SIGNAL_PHONE_NUMBER="+33111111111"
SIGNAL_ADMIN_NUMBER="+33222222222"
SIGNAL_RECIPIENT_NUMBER="+33333333333"
SIGNAL_GROUP_NAME="My Bot Group"

SignalCli Configuration

const { SignalCli } = require("signal-sdk");

// Basic configuration
const signal = new SignalCli(configPath, phoneNumber);
// configPath: Path to signal-cli config directory (optional)
// phoneNumber: Your registered Signal phone number (required)

// Example with custom config path
const signal = new SignalCli("/custom/signal-cli/config", "+33111111111");

SignalBot Configuration

const { SignalBot } = require("signal-sdk");

const bot = new SignalBot({
  phoneNumber: "+33111111111", // Required: Your Signal phone number
  admins: ["+33222222222"], // Required: Admin phone numbers
  group: {
    name: "My Bot Group", // Group name
    description: "Managed by my bot", // Group description
    createIfNotExists: true, // Create group if it doesn't exist
    avatar: "./group-avatar.jpg", // Group avatar image
  },
  settings: {
    commandPrefix: "/", // Command prefix (default: "/")
    logMessages: true, // Log incoming messages (default: false)
    welcomeNewMembers: true, // Welcome message for new members
    cooldownSeconds: 2, // Command cooldown in seconds
  },
});

Troubleshooting

Common Issues

1. signal-cli not found

   # Make sure signal-cli is installed and in your PATH
   # Download from: https://github.com/AsamK/signal-cli/releases
   signal-cli --version

2. Java not installed

   # Install Java (required by signal-cli)
   # Ubuntu/Debian
   sudo apt update && sudo apt install default-jre
   
   # macOS with Homebrew
   brew install openjdk
   
   # Windows: Download from Oracle or use package manager

3. Phone number not registered

   # Register your phone number with Signal first
   signal-cli -a +33111111111 register
   signal-cli -a +33111111111 verify CODE_FROM_SMS

4. Connection timeout

   # Test signal-cli directly
   signal-cli -a +33111111111 send +33222222222 "Test message"

5. Permission denied on config directory

   # Fix permissions on signal-cli config directory
   chmod -R 755 ~/.local/share/signal-cli/

Complete troubleshooting guide

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

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

Acknowledgments

• signal-cli - The underlying Signal CLI client
• Signal Protocol - The Signal messaging protocol
• The Signal community for their excellent work

Support

• Documentation: docs/
• Examples: examples/
• Issues: Report bugs and request features
• Contributing: See CONTRIBUTING.md

Built with TypeScript for the Signal community

API Methods

Compatible with signal-cli v0.13.23 - 100% Feature Coverage

| Category | Method | Description | Status | | --------------- | -------------------------- | ---------------------------------- | ------ | | Messaging | send | Send text messages and attachments | ✅ | | | sendReaction | React to messages with emoji | ✅ | | | sendTyping | Send typing indicators | ✅ | | | sendReceipt | Send read receipts | ✅ | | | sendPaymentNotification | Send payment notifications | ✅ | | | sendPollCreate | Create polls in conversations | ✅ | | | sendPollVote | Vote on existing polls | ✅ | | | sendPollTerminate | Terminate a poll | ✅ | | Groups | createGroup | Create new groups | ✅ | | | updateGroup | Update group settings | ✅ | | | listGroups | List all groups | ✅ | | | listGroupsDetailed | List groups with detailed info | ✅ | | | quitGroup | Leave a group | ✅ | | Contacts | listContacts | List all contacts | ✅ | | | updateContact | Update contact information | ✅ | | | removeContact | Remove contacts with options | ✅ | | | sendContacts | Export/send contact data | ✅ | | | block / unblock | Block/unblock contacts | ✅ | | | getUserStatus | Check registration status | ✅ | | Account | updateAccount | Update account settings | ✅ | | | listAccountsDetailed | List accounts with detailed info | ✅ | | Devices | listDevices | List linked devices | ✅ | | | updateDevice | Update device name (v0.13.23+) | ✅ | | Attachments | getAttachment | Retrieve attachment by ID | ✅ | | | getAvatar | Retrieve avatar by ID | ✅ | | | getSticker | Retrieve sticker by ID | ✅ | | Stickers | listStickerPacks | List sticker packs | ✅ | | | addStickerPack | Install sticker packs | ✅ | | | uploadStickerPack | Upload custom sticker packs | ✅ | | Advanced | submitRateLimitChallenge | Handle rate limiting | ✅ | | | startChangeNumber | Start phone number change | ✅ | | | finishChangeNumber | Complete phone number change | ✅ | | | sendMessageWithProgress | Enhanced messaging with progress | ✅ | | | sendNoteToSelf | Send message to own conversation | ✅ | | | unregister | Unregister account from server | ✅ | | Identities | listIdentities | List known identities | ✅ | | | trustIdentity | Mark identity as trusted | ✅ | | | getSafetyNumber | Get safety number for contact | ✅ | | | verifySafetyNumber | Verify and trust safety number | ✅ | | Multi-Account| addAccount | Add account to manager | ✅ | | | connectAll | Connect all managed accounts | ✅ | | | getStatus | Get status for all accounts | ✅ |

Complete API documentation

Support the Project

If you find signal sdk useful, consider supporting its development:

Your support helps maintain and improve signal-sdk

Made with ❤️ for the Signal community