✨ @itsliaaa/starcore

☕ For donation: Saweria

⚠️ Notice

This project is still in development and may contain bugs or incomplete features. If you encounter any issues, feel free to open an issue here

⚡ Quick Start

1. Install the packages

npm i @itsliaaa/starcore qr file-type

2. Create the client, store and handle events

import Client, { createSqliteStore } from '@itsliaaa/starcore'

/* createSqliteStore is compatible with bun:sqlite, node:sqlite, and better-sqlite3 */
const store = createSqliteStore()

const client = new Client({
  sessionId: 'main',
  store
})

// Display QR code for authentication
client.on('qr', ({ ascii }) => {
  console.log('📷 Scan this QR code')
  console.log(ascii)
})

// Called when authentication is successful
client.on('auth_paired', ({ id }) => {
  console.log('☁️ Paired as', id)
})

// Handle incoming messages
client.on('message', (m) => {
  const { chat, text } = m

  if (text === 'ping') {
    client.sendMessage(chat, '🏓 *Pong!*', { quote: m })
  }
})

// Connect to WhatsApp
await client.connect()

📕 Note: If no store is provided, the client automatically falls back to an in-memory store. The in-memory store is not persistent and will be cleared when the process exits. For persistent storage, use createSqliteStore() or createJsonStore().

Run the script and scan the QR code displayed in your terminal. Once the client is paired, incoming messages containing ping will receive a 🏓 *Pong!* reply.

👥 Multi-Session

Create multiple isolated sessions using a shared store. Each client is identified by a unique sessionId.

import Client, { createSqliteStore } from '@itsliaaa/starcore'

const store = createSqliteStore('./stores.sqlite')
const clients = new Map()

function createClient(sessionId) {
   if (clients.has(sessionId))
      return clients.get(sessionId)

   const client = new Client({
      sessionId,
      store
   })

   clients.set(sessionId, client)
   return client
}

const main = createClient('main')
const bot = createClient('bot')

for (const client of clients.values()) {
   client.on('qr', ({ ascii }) => {
      console.log('📷 Scan this QR code')
      console.log(ascii)
   })

   client.on('ready', () => {
      console.log(`✅ Session ${client.sessionId} is ready`)
   })
}

await Promise.all(
   [...clients.values()].map(client => client.connect())
)

⚙️ Configuration

const DEFAULT_CONFIG = {
  store: null,
  sessionId: null,
  phoneNumber: null,
  pairingCode: null,
  reconnect: {
    enabled: true,
    maxAttempts: 10,
    delayMs: 3000,
    resetAfterReconnectMs: 30000
  },
  linkPreview: {
    enabled: true,
    timeoutMs: 1000,
    thumbnailWidth: 255,
    uploadLargeThumbnail: false
  },
  message: {
    autoRead: false,
    decryptAddon: true,
    messageIdPrefix: 'STARCORE',
    newsletterAnnotation: null
  },
  media: {
    timeoutMs: 60000,
    detectDuration: true,
    generateThumbnail: true,
    generateWaveform: true,
    normalizeAudio: true,
    ffmpegPath: 'ffmpeg',
    ffprobePath: 'ffprobe',
    cache: null
  }
}

📡 Event References

client.on('connection', (ctx) => console.log('=> CONNECTION', ctx))
client.on('qr', (ctx) => console.log('=> QR', ctx))
client.on('pairing_code', (ctx) => console.log('=> PAIRING_CODE', ctx))
client.on('auth_paired', (ctx) => console.log('=> AUTH_PAIRED', ctx))
client.on('ready', () => console.log('=> SOCKET IS READY'))
client.on('message', (ctx) => console.log('=> MESSAGE', ctx))
client.on('message.addon', (ctx) => console.log('=> MESSAGE.ADDON', ctx))
client.on('message.edit', (ctx) => console.log('=> MESSAGE.EDIT', ctx))
client.on('message.delete', (ctx) => console.log('=> MESSAGE.DELETE', ctx))
client.on('message.stub', (ctx) => console.log('=> MESSAGE.STUB', ctx))
client.on('group.add', (ctx) => console.log('=> GROUP.ADD', ctx))
client.on('group.remove', (ctx) => console.log('=> GROUP.REMOVE', ctx))
client.on('group.promote', (ctx) => console.log('=> GROUP.PROMOTE', ctx))
client.on('group.demote', (ctx) => console.log('=> GROUP.DEMOTE', ctx))
client.on('group.join_request', (ctx) => console.log('=> GROUP.JOIN_REQUEST', ctx))
client.on('poll_update', (ctx) => console.log('=> POLL_UPDATE', ctx))
client.on('event_response', (ctx) => console.log('=> EVENT_RESPONSE', ctx))
client.on('call', (ctx) => console.log('=> CALL', ctx))
client.on('presence', (ctx) => console.log('=> PRESENCE', ctx))

📥 Updating WAProto

An outdated WAProto version may cause newer WhatsApp message features to fail when sending, such as hideParticipantName in Poll V6 and A2UI-based interactive messages.

To update WAProto to the latest available version:

import { updateWAProto } from '@itsliaaa/starcore'

await updateWAProto()

This ensures the latest WhatsApp protocol definitions are available to your application.