Signal SDK - TypeScript SDK for Signal Messenger

Features

$3

- 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

$3

- 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

$3

- 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

$3

``bash
npm install signal-sdk
`

$3

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

$3

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

`bash


View all available commands

`bash


Using npx (recommended)

`javascript
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();
`

$3

`javascript
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!");
`

$3

`javascript
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

$3

- Installation & Setup
- Getting Started Guide
- Device Linking

$3

- SignalCli Class
- SignalBot Class
- TypeScript Interfaces

$3

- 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

$3

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

Common Use Cases

$3

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

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

$3

`javascript
// 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"],
});
`

$3

`javascript
// 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",
});
`

$3

`javascript
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

$3

- 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

$3

- 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

$3

- 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.

$3

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

$3

| 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 |

$3

`bash


Run all tests

``

Development

`bash


Clone the repository

Create a .env file in your project root:

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

$3

`javascript
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");
`

$3

`javascript
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

$3

1. signal-cli not found

`bash
# 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

`bash
# 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

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

4. Connection timeout

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

5. Permission denied on config directory
`bash
# 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

---

$3

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


Your support helps maintain and improve signal-sdk

---

Made with ❤️ for the Signal community