smserver-client

TypeScript client for SMServer — the iMessage gateway for jailbroken iOS devices.

Uses got for HTTP and ws for WebSocket with full EventEmitter-based real-time events.

Install

npm install smserver-client

Example

import { SMServerClient } from "smserver-client";

const client = new SMServerClient({ httpPort: 8085, wsPort: 8081, password: "toor" });

await client.authenticate("toor");
await client.connect();

// Send a message
await client.sendMessage({ chat: "+15551234567", text: "Hey!" });

// Auto-reply "Pong" when someone sends "Ping"
client.on("newMessage", async (msg) => {
  if (!msg.is_from_me && msg.text?.trim().toLowerCase() === "ping") {
    await client.sendMessage({ chat: msg.chat_identifier, text: "Pong" });
  }
});

Quick Start

import { SMServerClient } from "smserver-client";

// Full URLs
const client = new SMServerClient({
  baseUrl: "http://localhost:8085",
  wsUrl: "ws://localhost:8081",
  password: "toor",
});

// Or just ports (host defaults to localhost)
const client = new SMServerClient({
  httpPort: 8085,
  wsPort: 8081,
  password: "toor",
});

// Remote device
const client = new SMServerClient({
  host: "192.168.1.50",
  httpPort: 8741,
  wsPort: 8740,
  password: "toor",
});

// Authenticate
await client.authenticate("toor");

// Get recent chats
const chats = await client.getChats();
console.log(chats);

// Get messages from a conversation
const messages = await client.getMessages("+15551234567", {
  numMessages: 50,
});
console.log(messages);

// Send a text
await client.sendMessage({
  chat: "+15551234567",
  text: "Hello from Node.js!",
});

// Connect WebSocket for real-time events
await client.connect();

client.on("newMessage", (msg) => {
  console.log("New message:", msg.text, "from", msg.chat_identifier);
});

client.on("messageTyping", ({ chat, active }) => {
  console.log(chat, active ? "is typing..." : "stopped typing");
});

client.on("messageViewed", ({ guid, date_read }) => {
  console.log("Message", guid, "read at", date_read);
});

client.on("batteryStatus", ({ percentage, charging }) => {
  console.log(`Battery: ${percentage}%`, charging ? "(charging)" : "");
});

API

new SMServerClient(options?)

| Option | Default | Description | |--------|---------|-------------| | baseUrl | http://localhost:8085 | SMServer HTTP API URL | | wsUrl | ws://localhost:8081 | SMServer WebSocket URL | | host | localhost | Host for port-based shorthand | | httpPort | — | HTTP port — auto-generates baseUrl | | wsPort | — | WebSocket port — auto-generates wsUrl | | password | — | Auto-authenticate on construction |

REST Methods

All methods return Promises.

| Method | Description | |--------|-------------| | authenticate(password) | Authenticate with server password | | getMessages(chatId, opts?) | Get messages for a chat | | getChats(opts?) | List recent conversations | | getConversation(chatId) | Get conversation details | | getName(chatId) | Resolve display name for a chat ID | | searchMessages(term, opts?) | Full-text search across messages | | matchContacts(value, type?) | Find contacts by partial match | | getPhotos(opts?) | List camera roll photos | | getConfig() | Get server configuration | | sendMessage(params) | Send a text/attachment message | | sendTapback(type, guid, remove?) | Send/remove message reaction | | deleteChat(chatId) | Delete entire conversation | | deleteText(guid) | Delete a single message | | getAttachment(path) | Download attachment file as Buffer | | getProfilePicture(chatId) | Download profile picture as Buffer | | getPhotoFile(path) | Download camera roll photo as Buffer |

WebSocket Events

client.on("newMessage",       (msg: Message) => {})
client.on("messageTyping",    (ev: TypingEvent) => {})
client.on("messageViewed",    (ev: MessageReadEvent) => {})
client.on("batteryStatus",    (ev: BatteryEvent) => {})
client.on("tapbackSent",      (ev: TapbackEvent) => {})
client.on("connected",        () => {})
client.on("disconnected",     (code: number, reason: string) => {})
client.on("error",            (err: Error) => {})

WebSocket Methods

| Method | Description | |--------|-------------| | connect() | Open WebSocket connection | | disconnect() | Close WebSocket connection | | sendTyping(chat, active) | Send typing indicator |

Build

npm run build        # tsdown (ESM + CJS + types)
npm run typecheck    # tsc --noEmit
npm run debug        # interactive WebSocket message monitor
npm run debug:headless  # non-interactive (just log to file)

Debug Server

Built-in WebSocket monitor that logs every message type and saves raw JSONL:

npm run debug

# Custom endpoints
npm run debug -- --ws ws://192.168.1.50:8081 --http http://192.168.1.50:8085

# Custom output directory
npm run debug -- --out ./my-session

Interactive commands: s = print stats, r = reconnect, q = quit. Raw messages saved to ./debug-output/raw-<timestamp>.jsonl.

License

MIT