kersiosocket 0.0.0-stage → 0.6.0-dev

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "kersiosocket",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.0-dev",
+  "description": "Unified multi-engine WhatsApp Web client facade with Zapo-JS, Baileys, Go whatsmeow JSONL bridge, hardened native research transport, session archive and lock manager.",
+  "main": "src/index.js",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\"",
+    "test:serial": "node --test --test-concurrency=1 \"test/*.test.js\"",
+    "refresh:tokens": "node scripts/import-token-table.js",
+    "bench:wabinary": "node bench/wabinary.js",
+    "test:backends": "node --test test/unified-client.test.js test/backend-adapters.test.js test/whatsmeow-process.test.js"
+  },
+  "peerDependencies": {
+    "ws": ">=8",
+    "zapo-js": ">=1.0.0",
+    "@whiskeysockets/baileys": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    },
+    "zapo-js": {
+      "optional": true
+    },
+    "@whiskeysockets/baileys": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}

package/scripts/import-token-table.js

@@ -0,0 +1,95 @@
+'use strict'
+
+const crypto = require('node:crypto')
+const fs = require('node:fs/promises')
+const path = require('node:path')
+const { parseGoTokenTable, validateTokenTable } = require('../src/wabinary/token-source')
+
+// Deliberately pinned to an immutable upstream commit, never to a moving branch.
+const SOURCE = Object.freeze({
+  repository: 'tulir/whatsmeow',
+  commit: 'b2b1e71d45e2ff171153b025b5a42f475bb30ef8',
+  file: 'binary/token/token.go',
+  blobSha1: '361acd19d93c8dea30f516e27ce8c77fdaecc56f',
+  dictVersion: 3,
+  license: 'MPL-2.0'
+})
+const RAW_BASE = `https://raw.githubusercontent.com/${SOURCE.repository}/${SOURCE.commit}`
+
+async function fetchText(url) {
+  const response = await fetch(url, { signal: AbortSignal.timeout(20000) })
+  if (!response.ok) throw new Error(`download gagal (${response.status}) untuk ${url}`)
+  return response.text()
+}
+
+function gitBlobSha1(text) {
+  const bytes = Buffer.from(text, 'utf8')
+  return crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex')
+}
+
+async function atomicWrite(filePath, contents) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true })
+  const temp = `${filePath}.${process.pid}.tmp`
+  try {
+    await fs.writeFile(temp, contents, { encoding: 'utf8', flag: 'wx' })
+    await fs.rename(temp, filePath)
+  } catch (error) {
+    await fs.rm(temp, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+async function main() {
+  const root = path.resolve(__dirname, '..')
+  const sourceUrl = `${RAW_BASE}/${SOURCE.file}`
+  const sourceText = await fetchText(sourceUrl)
+  const observedSha = gitBlobSha1(sourceText)
+  if (observedSha !== SOURCE.blobSha1) {
+    throw new Error(`source hash mismatch; expected ${SOURCE.blobSha1}, received ${observedSha}. Refusing to import.`)
+  }
+
+  const parsed = parseGoTokenTable(sourceText)
+  validateTokenTable(parsed, { dictVersion: SOURCE.dictVersion })
+
+  const licenseUrl = `${RAW_BASE}/LICENSE`
+  const licenseText = await fetchText(licenseUrl)
+  if (!licenseText.startsWith('Mozilla Public License Version 2.0')) {
+    throw new Error('lisensi sumber tidak cocok dengan MPL-2.0; impor dibatalkan')
+  }
+
+  const licensePath = path.join(root, 'licenses', 'whatsmeow-MPL-2.0.txt')
+  await atomicWrite(licensePath, licenseText)
+
+  const tokenJson = {
+    _metadata: {
+      kind: 'third-party protocol token data',
+      upstream: SOURCE.repository,
+      upstreamFile: SOURCE.file,
+      upstreamCommit: SOURCE.commit,
+      upstreamBlobSha1: SOURCE.blobSha1,
+      dictVersion: parsed.dictVersion,
+      license: SOURCE.license,
+      licenseFile: 'licenses/whatsmeow-MPL-2.0.txt',
+      importedAt: new Date().toISOString(),
+      verification: 'Pinned source and Git blob hash checked; not independently confirmed against a live WhatsApp server build.',
+      implementationNote: 'KersioSocket WABinary encoder/decoder implementation remains separate; this file contains sourced token data.'
+    },
+    single: parsed.single,
+    double: parsed.double
+  }
+  const tablePath = path.join(root, 'src', 'wabinary', 'tokens.json')
+  await atomicWrite(tablePath, `${JSON.stringify(tokenJson, null, 2)}\n`)
+
+  console.log('Token table imported and validated.')
+  console.log(`Source: ${SOURCE.repository}/${SOURCE.file}@${SOURCE.commit}`)
+  console.log(`DictVersion: ${parsed.dictVersion}`)
+  console.log(`Single entries: ${parsed.single.length}`)
+  console.log(`Double pages: ${parsed.double.length} x ${parsed.double[0].length}`)
+  console.log(`Source Git blob SHA-1: ${observedSha}`)
+  console.log('Notice: this is a version-pinned public reverse-engineering dataset, not an official WhatsApp-issued compatibility guarantee.')
+}
+
+main().catch((error) => {
+  console.error(`Import token table gagal: ${error.message}`)
+  process.exitCode = 1
+})

package/src/backends/baileys.js

@@ -0,0 +1,121 @@
+'use strict'
+
+const { BaseBackend } = require('./base')
+
+const BAILEYS_EVENTS = Object.freeze([
+  'connection.update', 'creds.update', 'messages.upsert', 'messages.update',
+  'messages.delete', 'message-receipt.update', 'contacts.upsert', 'contacts.update',
+  'chats.upsert', 'chats.update', 'groups.upsert', 'groups.update',
+  'group-participants.update', 'messaging-history.set', 'presence.update', 'blocklist.set'
+])
+
+/** Adapter ke socket @whiskeysockets/baileys; auth state tetap dimiliki Baileys. */
+class BaileysBackend extends BaseBackend {
+  constructor(socket, { baileysModule = null } = {}) {
+    super('baileys')
+    if (!socket || !socket.ev || typeof socket.ev.on !== 'function' || typeof socket.sendMessage !== 'function') {
+      throw new TypeError('BaileysBackend memerlukan socket Baileys yang menyediakan ev.on() dan sendMessage()')
+    }
+    this.socket = socket
+    this.module = baileysModule
+    for (const name of BAILEYS_EVENTS) {
+      this.subscribe(socket.ev, name, (payload) => this._forward(name, payload))
+    }
+  }
+
+  static async create({ socket, socketOptions = {}, baileysModule } = {}) {
+    let mod = baileysModule
+    if (!socket) {
+      if (!mod) {
+        try { mod = await import('@whiskeysockets/baileys') } catch (error) {
+          throw dependencyError('@whiskeysockets/baileys', 'BaileysBackend', error)
+        }
+      }
+      const factory = mod.default || mod.makeWASocket || mod.makeSocket
+      if (typeof factory !== 'function') throw new TypeError('Modul Baileys tidak mengekspor factory socket yang dikenal')
+      socket = factory(socketOptions)
+    }
+    return new BaileysBackend(socket, { baileysModule: mod })
+  }
+
+  _forward(name, payload) {
+    this.emitSafe(name, payload)
+    if (name === 'connection.update' && payload && payload.qr) {
+      this.emitSafe('pairing.qr', { qr: payload.qr, engine: this.engine })
+    }
+    if (name === 'connection.update' && payload && payload.pairingCode) {
+      this.emitSafe('pairing.code', { code: payload.pairingCode, engine: this.engine })
+    }
+    if (name === 'messages.upsert' && payload && Array.isArray(payload.messages)) {
+      for (const message of payload.messages) this.emitSafe('message', message)
+    }
+    if (name === 'creds.update') this.emitSafe('credentials.update', payload)
+  }
+
+  async connect() {
+    if (this._closed) throw new Error('BaileysBackend sudah ditutup')
+    // makeWASocket starts its connection when created; there may be no connect() method.
+    if (typeof this.socket.connect === 'function') await this.socket.connect()
+    return this
+  }
+
+  async sendMessage(jid, content, options) {
+    const normalized = typeof content === 'string' ? { text: content } : content
+    return options === undefined
+      ? this.socket.sendMessage(jid, normalized)
+      : this.socket.sendMessage(jid, normalized, options)
+  }
+
+  async requestPairingCode(phoneNumber) {
+    if (typeof this.socket.requestPairingCode !== 'function') return this.unsupported('requestPairingCode')
+    if (typeof phoneNumber !== 'string' || !/^\d{8,15}$/.test(phoneNumber)) {
+      throw new TypeError('phoneNumber wajib berupa digit saja, termasuk kode negara, sepanjang 8–15 digit')
+    }
+    return this.socket.requestPairingCode(phoneNumber)
+  }
+
+  async downloadMedia(message, options) {
+    if (typeof this.module?.downloadMediaMessage !== 'function') return this.unsupported('downloadMedia')
+    const type = options?.type || 'buffer'
+    return this.module.downloadMediaMessage(message, type, options?.options || {}, options?.context || {})
+  }
+
+  async invoke(method, ...args) {
+    if (typeof method !== 'string' || !/^[a-zA-Z_$][\w$]*$/.test(method)) throw new TypeError('method capability tidak valid')
+    const fn = this.socket[method]
+    if (typeof fn !== 'function') return this.unsupported(method)
+    return fn.apply(this.socket, args)
+  }
+
+  async close() {
+    if (this._closed) return
+    this._closed = true
+    this.detachSubscriptions()
+    if (typeof this.socket.end === 'function') await this.socket.end()
+    else if (typeof this.socket.close === 'function') await this.socket.close()
+    else if (this.socket.ws && typeof this.socket.ws.close === 'function') this.socket.ws.close()
+    this.removeAllListeners()
+  }
+
+  capabilities() {
+    return {
+      engine: this.engine,
+      live: true,
+      messaging: typeof this.socket.sendMessage === 'function',
+      media: typeof this.module?.downloadMediaMessage === 'function',
+      groups: typeof this.socket.groupMetadata === 'function' || typeof this.socket.groupCreate === 'function',
+      historySync: true,
+      authQr: true,
+      authPairingCode: typeof this.socket.requestPairingCode === 'function'
+    }
+  }
+}
+
+function dependencyError(pkg, adapter, cause) {
+  const error = new Error(`${adapter} membutuhkan dependency opsional '${pkg}'. Instal dependency itu atau berikan instance client/socket yang sudah dibuat.`)
+  error.code = 'ERR_OPTIONAL_DEPENDENCY_MISSING'
+  error.cause = cause
+  return error
+}
+
+module.exports = { BaileysBackend }

package/src/backends/base.js

@@ -0,0 +1,102 @@
+'use strict'
+
+const { EventEmitter } = require('node:events')
+
+const NORMALIZED_EVENTS = Object.freeze([
+  'connection.update', 'pairing.qr', 'pairing.code', 'pairing.success',
+  'messages.upsert', 'messages.update', 'messages.delete', 'message',
+  'message.receipt', 'contacts.upsert', 'contacts.update', 'chats.upsert',
+  'chats.update', 'groups.upsert', 'groups.update', 'group-participants.update',
+  'messaging-history.set', 'creds.update', 'protocol.error', 'backend.error'
+])
+
+class BackendNotSupportedError extends Error {
+  constructor(engine, capability) {
+    super(`Backend '${engine}' tidak menyediakan capability '${capability}'`)
+    this.name = 'BackendNotSupportedError'
+    this.code = 'ERR_BACKEND_CAPABILITY_UNSUPPORTED'
+    this.engine = engine
+    this.capability = capability
+  }
+}
+
+class BaseBackend extends EventEmitter {
+  constructor(engine) {
+    super()
+    this.engine = engine
+    this._subscriptions = []
+    this._closed = false
+    this._lastEvents = new Map()
+  }
+
+  subscribe(emitter, event, handler) {
+    if (!emitter || typeof emitter.on !== 'function') return
+    emitter.on(event, handler)
+    this._subscriptions.push(() => {
+      if (typeof emitter.off === 'function') emitter.off(event, handler)
+      else if (typeof emitter.removeListener === 'function') emitter.removeListener(event, handler)
+    })
+  }
+
+  detachSubscriptions() {
+    for (const off of this._subscriptions.splice(0)) {
+      try { off() } catch { /* best-effort listener cleanup */ }
+    }
+  }
+
+  emitSafe(event, payload) {
+    if (event === 'pairing.success' || (event === 'connection.update' && payload?.connection === 'close')) {
+      this._lastEvents.delete('pairing.qr')
+      this._lastEvents.delete('pairing.code')
+    }
+    if (['connection.update', 'pairing.qr', 'pairing.code', 'pairing.success'].includes(event)) this._lastEvents.set(event, payload)
+    // A consumer listener must not crash the protocol/event source.
+    for (const listener of this.rawListeners(event)) {
+      try { listener.call(this, payload) } catch (error) {
+        if (event !== 'backend.error') {
+          for (const onError of this.rawListeners('backend.error')) {
+            try { onError.call(this, { error, sourceEvent: event }) } catch { /* isolate listeners */ }
+          }
+        }
+      }
+    }
+  }
+
+  replay(event, listener) {
+    if (this._lastEvents.has(event)) listener(this._lastEvents.get(event))
+  }
+
+  unsupported(capability) { throw new BackendNotSupportedError(this.engine, capability) }
+
+  async connect() { this.unsupported('connect') }
+  async close() { this._closed = true; this.detachSubscriptions() }
+  async sendMessage() { this.unsupported('sendMessage') }
+  async requestPairingCode() { this.unsupported('requestPairingCode') }
+  async downloadMedia() { this.unsupported('downloadMedia') }
+  async invoke() { this.unsupported('invoke') }
+
+  capabilities() {
+    return { engine: this.engine, live: false, messaging: false, media: false, groups: false, historySync: false }
+  }
+}
+
+function assertJid(jid) {
+  if (typeof jid !== 'string' || !jid.trim() || jid.length > 256 || /[\r\n\0]/.test(jid)) {
+    throw new TypeError('jid harus string non-kosong dan tidak mengandung control character')
+  }
+  return jid
+}
+
+function assertMessageContent(content) {
+  if (typeof content === 'string') {
+    if (!content.length) throw new TypeError('teks pesan tidak boleh kosong')
+    return content
+  }
+  if (!content || typeof content !== 'object' || Array.isArray(content) || Buffer.isBuffer(content)) {
+    throw new TypeError('content harus string atau objek konten pesan')
+  }
+  if (Object.keys(content).length === 0) throw new TypeError('content pesan tidak boleh kosong')
+  return content
+}
+
+module.exports = { BaseBackend, BackendNotSupportedError, NORMALIZED_EVENTS, assertJid, assertMessageContent }

package/src/backends/whatsmeow-process.js

@@ -0,0 +1,202 @@
+'use strict'
+
+const { spawn } = require('node:child_process')
+const { randomUUID } = require('node:crypto')
+const { BaseBackend } = require('./base')
+
+const DEFAULT_MAX_LINE_BYTES = 16 * 1024 * 1024
+
+/**
+ * JSONL-RPC transport for a user-supplied Go process that wraps tulir/whatsmeow.
+ * This is transport/normalization only: the companion executable is not bundled,
+ * and this class never pretends to implement the WhatsApp protocol in JavaScript.
+ */
+class WhatsmeowProcessBackend extends BaseBackend {
+  constructor({ command, args = [], cwd, env, sessionId = 'default', requestTimeoutMs = 30000, maxPending = 256, maxLineBytes = DEFAULT_MAX_LINE_BYTES, spawnImpl = spawn } = {}) {
+    super('whatsmeow-go')
+    if (typeof command !== 'string' || !command.trim()) throw new TypeError('command executable Go bridge wajib diisi')
+    if (!Array.isArray(args) || args.some((x) => typeof x !== 'string')) throw new TypeError('args harus array string')
+    if (!Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs < 1) throw new RangeError('requestTimeoutMs harus integer positif')
+    if (!Number.isSafeInteger(maxPending) || maxPending < 1) throw new RangeError('maxPending harus integer positif')
+    if (!Number.isSafeInteger(maxLineBytes) || maxLineBytes < 1024) throw new RangeError('maxLineBytes minimal 1024')
+    this.options = { command, args: [...args], cwd, env, sessionId, requestTimeoutMs, maxPending, maxLineBytes, spawnImpl }
+    this.child = null
+    this.pending = new Map()
+    this.counter = 0
+    this.buffer = ''
+    this._spawned = false
+    this._exitPromise = null
+  }
+
+  async connect() {
+    if (this._closed) throw new Error('WhatsmeowProcessBackend sudah ditutup')
+    if (this.child) return this
+    const { command, args, cwd, env, spawnImpl } = this.options
+    const child = spawnImpl(command, args, {
+      cwd,
+      env: env ? { ...process.env, ...env } : process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: false,
+      windowsHide: true
+    })
+    this.child = child
+    this._exitPromise = new Promise((resolve) => child.once('close', (code, signal) => resolve({ code, signal })))
+    child.stdout.on('data', (chunk) => this._onStdout(chunk))
+    child.stderr.on('data', (chunk) => this.emitSafe('bridge.stderr', Buffer.from(chunk).toString('utf8')))
+    child.on('error', (error) => this._failAll(error))
+    child.on('close', (code, signal) => {
+      const error = new Error(`whatsmeow bridge ditutup (code=${code}, signal=${signal || 'none'})`)
+      this._failAll(error)
+      this.emitSafe('connection.update', { connection: 'close', error, code, signal })
+    })
+    await new Promise((resolve, reject) => {
+      if (child.pid) return resolve()
+      const onSpawn = () => { cleanup(); resolve() }
+      const onError = (error) => { cleanup(); reject(error) }
+      const cleanup = () => { child.off('spawn', onSpawn); child.off('error', onError) }
+      child.once('spawn', onSpawn)
+      child.once('error', onError)
+    })
+    await this.request('connect', { sessionId: this.options.sessionId })
+    this.emitSafe('connection.update', { connection: 'open', engine: this.engine })
+    return this
+  }
+
+  _onStdout(chunk) {
+    this.buffer += Buffer.from(chunk).toString('utf8')
+    if (Buffer.byteLength(this.buffer, 'utf8') > this.options.maxLineBytes && !this.buffer.includes('\n')) {
+      this._failAll(new Error('whatsmeow bridge mengirim JSONL melebihi batas ukuran'))
+      if (this.child && !this.child.killed) this.child.kill()
+      this.buffer = ''
+      return
+    }
+    let newline
+    while ((newline = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, newline)
+      this.buffer = this.buffer.slice(newline + 1)
+      if (Buffer.byteLength(line, 'utf8') > this.options.maxLineBytes) {
+        this._failAll(new Error('whatsmeow bridge mengirim baris JSONL terlalu besar'))
+        if (this.child && !this.child.killed) this.child.kill()
+        return
+      }
+      if (!line.trim()) continue
+      this._handleLine(line)
+    }
+  }
+
+  _handleLine(line) {
+    let message
+    try { message = JSON.parse(line) } catch (error) {
+      this.emitSafe('protocol.error', new Error(`JSONL bridge tidak valid: ${error.message}`))
+      return
+    }
+    if (!message || typeof message !== 'object' || Array.isArray(message)) {
+      this.emitSafe('protocol.error', new Error('JSONL bridge harus berupa objek JSON'))
+      return
+    }
+    if (typeof message.event === 'string') {
+      this.emitSafe(message.event, message.data)
+      if (message.event === 'messages.upsert' && Array.isArray(message.data?.messages)) {
+        for (const row of message.data.messages) this.emitSafe('message', row)
+      }
+      return
+    }
+    const pending = this.pending.get(String(message.id ?? ''))
+    if (!pending) {
+      this.emitSafe('protocol.warning', { reason: 'unknown-response-id', id: message.id })
+      return
+    }
+    this.pending.delete(String(message.id))
+    clearTimeout(pending.timer)
+    if (message.error) {
+      const error = new Error(String(message.error.message || 'whatsmeow bridge error'))
+      if (message.error.code != null) error.code = String(message.error.code)
+      pending.reject(error)
+    } else pending.resolve(message.result)
+  }
+
+  request(method, params = {}, { timeoutMs = this.options.requestTimeoutMs, signal } = {}) {
+    if (!this.child || !this.child.stdin || this.child.stdin.destroyed) return Promise.reject(new Error('whatsmeow bridge belum terhubung'))
+    if (this.pending.size >= this.options.maxPending) return Promise.reject(new Error('jumlah request bridge pending sudah mencapai batas'))
+    if (typeof method !== 'string' || !/^[a-zA-Z][\w.-]{0,127}$/.test(method)) return Promise.reject(new TypeError('nama method RPC tidak valid'))
+    if (signal?.aborted) return Promise.reject(signal.reason || new Error('request dibatalkan'))
+    const id = `${++this.counter}-${randomUUID()}`
+    const wire = JSON.stringify({ id, method, params: jsonSafe(params) }) + '\n'
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id)
+        cleanup()
+        reject(new Error(`timeout bridge RPC '${method}' setelah ${timeoutMs} ms`))
+      }, timeoutMs)
+      const onAbort = () => {
+        this.pending.delete(id)
+        clearTimeout(timer)
+        cleanup()
+        reject(signal.reason || new Error('request dibatalkan'))
+      }
+      const cleanup = () => signal?.removeEventListener('abort', onAbort)
+      signal?.addEventListener('abort', onAbort, { once: true })
+      this.pending.set(id, { resolve: (v) => { cleanup(); resolve(v) }, reject: (e) => { cleanup(); reject(e) }, timer })
+      this.child.stdin.write(wire, (error) => {
+        if (!error) return
+        const pending = this.pending.get(id)
+        if (!pending) return
+        this.pending.delete(id)
+        clearTimeout(timer)
+        cleanup()
+        reject(error)
+      })
+    })
+  }
+
+  _failAll(error) {
+    for (const [id, pending] of this.pending) {
+      this.pending.delete(id)
+      clearTimeout(pending.timer)
+      pending.reject(error)
+    }
+  }
+
+  async sendMessage(jid, content, options) {
+    return this.request('sendMessage', { jid, content, ...(options === undefined ? {} : { options }) })
+  }
+
+  async requestPairingCode(phoneNumber) { return this.request('requestPairingCode', { phoneNumber }) }
+  async downloadMedia(message, options) { return this.request('downloadMedia', { message, options }) }
+  async invoke(method, ...args) { return this.request('invoke', { method, args }) }
+  async capabilities() {
+    try { return { engine: this.engine, ...(await this.request('capabilities', {})) } }
+    catch { return { engine: this.engine, live: true, messaging: true, media: false, groups: false, historySync: false, remoteCapabilitiesUnknown: true } }
+  }
+
+  async close() {
+    if (this._closed) return
+    this._closed = true
+    if (this.child && !this.child.killed && this.child.stdin && !this.child.stdin.destroyed) {
+      try { await this.request('close', {}, { timeoutMs: Math.min(2000, this.options.requestTimeoutMs) }) } catch { /* process may exit after its close response */ }
+    }
+    this.detachSubscriptions()
+    this._failAll(new Error('WhatsmeowProcessBackend ditutup'))
+    if (this.child && !this.child.killed) this.child.kill()
+    this.removeAllListeners()
+  }
+}
+
+function jsonSafe(value, seen = new WeakSet()) {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) return { $base64: Buffer.from(value).toString('base64') }
+  if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number') return value
+  if (typeof value === 'bigint') return value.toString()
+  if (typeof value !== 'object') throw new TypeError(`nilai tidak dapat dikirim melalui bridge JSON: ${typeof value}`)
+  if (seen.has(value)) throw new TypeError('objek siklik tidak bisa dikirim melalui bridge JSON')
+  seen.add(value)
+  let result
+  if (Array.isArray(value)) result = value.map((v) => jsonSafe(v, seen))
+  else {
+    result = {}
+    for (const [key, child] of Object.entries(value)) result[key] = jsonSafe(child, seen)
+  }
+  seen.delete(value)
+  return result
+}
+
+module.exports = { WhatsmeowProcessBackend, jsonSafe, DEFAULT_MAX_LINE_BYTES }

package/src/backends/zapo.js

@@ -0,0 +1,123 @@
+'use strict'
+
+const { BaseBackend } = require('./base')
+
+const ZAPO_EVENTS = Object.freeze([
+  'auth_qr', 'auth_paired', 'auth_pairing_code', 'connection.update',
+  'message', 'messages.upsert', 'messages.update', 'messages.delete',
+  'contacts.upsert', 'contacts.update', 'chats.upsert', 'chats.update',
+  'groups.upsert', 'groups.update', 'group-participants.update',
+  'messaging-history.set', 'creds.update', 'error'
+])
+
+/**
+ * Adapter ke API publik zapo-js. Tidak menyalin atau mengubah sesi/protokol Zapo;
+ * satu WaClient tetap menjadi pemilik state autentikasi dan Signal.
+ */
+class ZapoBackend extends BaseBackend {
+  constructor(client, { sessionId = 'default' } = {}) {
+    super('zapo-js')
+    if (!client || typeof client.on !== 'function' || !client.message || typeof client.message.send !== 'function') {
+      throw new TypeError('ZapoBackend memerlukan WaClient zapo-js dengan .on() dan .message.send()')
+    }
+    this.client = client
+    this.sessionId = sessionId
+    for (const name of ZAPO_EVENTS) {
+      this.subscribe(client, name, (payload) => this._forward(name, payload))
+    }
+  }
+
+  _forward(name, payload) {
+    if (name === 'auth_qr') {
+      const qr = payload && typeof payload === 'object' ? payload.qr : payload
+      if (qr !== undefined) this.emitSafe('pairing.qr', { qr, raw: payload, engine: this.engine })
+      return
+    }
+    if (name === 'auth_pairing_code') {
+      const code = payload && typeof payload === 'object' ? payload.code : payload
+      if (code !== undefined) this.emitSafe('pairing.code', { code, raw: payload, engine: this.engine })
+      return
+    }
+    if (name === 'auth_paired') {
+      this.emitSafe('pairing.success', { ...asObject(payload), raw: payload, engine: this.engine })
+      this.emitSafe('connection.update', { connection: 'open', engine: this.engine, authenticated: true })
+      return
+    }
+    if (name === 'message') {
+      this.emitSafe('connection.update', { connection: 'open', engine: this.engine, observedMessage: true })
+      this.emitSafe('message', payload)
+      if (payload && payload.key) this.emitSafe('messages.upsert', { type: 'notify', messages: [payload], engine: this.engine })
+      return
+    }
+    if (name === 'error') {
+      this.emitSafe('backend.error', { error: payload instanceof Error ? payload : new Error(String(payload)), engine: this.engine })
+      return
+    }
+    this.emitSafe(name, payload)
+  }
+
+  async connect() {
+    if (this._closed) throw new Error('ZapoBackend sudah ditutup')
+    if (typeof this.client.connect !== 'function') this.unsupported('connect')
+    await this.client.connect()
+    return this
+  }
+
+  async sendMessage(jid, content, options) {
+    if (options === undefined) return this.client.message.send(jid, content)
+    return this.client.message.send(jid, content, options)
+  }
+
+  async requestPairingCode(phoneNumber) {
+    if (typeof this.client.requestPairingCode === 'function') return this.client.requestPairingCode(phoneNumber)
+    if (typeof this.client.auth?.requestPairingCode === 'function') return this.client.auth.requestPairingCode(phoneNumber)
+    return this.unsupported('requestPairingCode')
+  }
+
+  async downloadMedia(message, options) {
+    if (typeof this.client.media?.download === 'function') return this.client.media.download(message, options)
+    if (typeof this.client.message?.downloadMedia === 'function') return this.client.message.downloadMedia(message, options)
+    return this.unsupported('downloadMedia')
+  }
+
+  async invoke(path, ...args) {
+    if (typeof path !== 'string' || !/^[a-zA-Z_$][\w$]*(\.[a-zA-Z_$][\w$]*)*$/.test(path)) {
+      throw new TypeError('path capability tidak valid')
+    }
+    const parts = path.split('.')
+    let owner = this.client
+    for (const part of parts.slice(0, -1)) {
+      if (!owner || typeof owner !== 'object') return this.unsupported(path)
+      owner = owner[part]
+    }
+    const fn = owner && owner[parts[parts.length - 1]]
+    if (typeof fn !== 'function') return this.unsupported(path)
+    return fn.apply(owner, args)
+  }
+
+  async close() {
+    if (this._closed) return
+    this._closed = true
+    this.detachSubscriptions()
+    const close = this.client.disconnect || this.client.close || this.client.end
+    if (typeof close === 'function') await close.call(this.client)
+    this.removeAllListeners()
+  }
+
+  capabilities() {
+    return {
+      engine: this.engine,
+      live: typeof this.client.connect === 'function',
+      messaging: typeof this.client.message?.send === 'function',
+      media: Boolean(this.client.media || this.client.message?.downloadMedia),
+      groups: Boolean(this.client.group || this.client.groups),
+      historySync: Boolean(this.client.history || this.client.sync),
+      authQr: true,
+      authPairingCode: typeof this.client.requestPairingCode === 'function' || typeof this.client.auth?.requestPairingCode === 'function'
+    }
+  }
+}
+
+function asObject(value) { return value && typeof value === 'object' ? value : { value } }
+
+module.exports = { ZapoBackend }