kersiosocket 0.0.0-stage → 0.6.0-dev

package/src/client/kersio-client.js

@@ -0,0 +1,305 @@
+'use strict'
+
+const { EventEmitter } = require('node:events')
+const { assertJid, assertMessageContent, BackendNotSupportedError } = require('../backends/base')
+const { ZapoBackend } = require('../backends/zapo')
+const { BaileysBackend } = require('../backends/baileys')
+const { WhatsmeowProcessBackend } = require('../backends/whatsmeow-process')
+
+const EVENT_FORWARD = [
+  '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', 'credentials.update', 'protocol.error',
+  'protocol.warning', 'backend.error', 'bridge.stderr'
+]
+
+class KersioClient extends EventEmitter {
+  constructor(backend, { sessionId = 'default', archive = null } = {}) {
+    super()
+    if (!backend || typeof backend.sendMessage !== 'function' || typeof backend.connect !== 'function') {
+      throw new TypeError('KersioClient membutuhkan backend adapter yang valid')
+    }
+    this.backend = backend
+    this.engine = backend.engine || 'custom'
+    this.sessionId = sessionId
+    this.archive = archive
+    this._lastReplayable = new Map()
+    this.state = 'idle'
+    this._closed = false
+    this._unsubs = []
+    for (const event of EVENT_FORWARD) {
+      const handler = (payload) => {
+        if (event === 'connection.update' && payload && typeof payload.connection === 'string') {
+          if (payload.connection === 'open' || payload.connection === 'noise-ready') this.state = 'open'
+          else if (payload.connection === 'close') this.state = 'close'
+          else if (payload.connection === 'connecting' || payload.connection === 'handshaking') this.state = 'connecting'
+          this._emitSafely('client.state', { state: this.state, engine: this.engine, update: payload })
+        }
+        this._emitSafely(event, payload)
+        if (event === 'messages.upsert' && this.archive && payload && Array.isArray(payload.messages)) {
+          this._archiveMessages(payload.messages).catch((error) => this._emitSafely('archive.error', error))
+        }
+      }
+      backend.on(event, handler)
+      this._unsubs.push(() => backend.off(event, handler))
+      if (typeof backend.replay === 'function') backend.replay(event, handler)
+    }
+  }
+
+  on(event, listener) {
+    super.on(event, listener)
+    if (this._lastReplayable.has(event)) {
+      const payload = this._lastReplayable.get(event)
+      queueMicrotask(() => {
+        if (this._closed || this.listeners(event).length === 0) return
+        try { Reflect.apply(listener, this, [payload]) } catch (error) {
+          if (event !== 'client.error') this._emitSafely('client.error', { error, sourceEvent: event })
+        }
+      })
+    }
+    return this
+  }
+
+  _emitSafely(event, payload) {
+    if (event === 'pairing.success' || (event === 'connection.update' && payload?.connection === 'close')) {
+      this._lastReplayable.delete('pairing.qr')
+      this._lastReplayable.delete('pairing.code')
+    }
+    if (['connection.update', 'pairing.qr', 'pairing.code', 'pairing.success'].includes(event)) this._lastReplayable.set(event, payload)
+    for (const listener of this.rawListeners(event)) {
+      try { listener.call(this, payload) } catch (error) {
+        if (event !== 'client.error') {
+          for (const onError of this.rawListeners('client.error')) {
+            try { onError.call(this, { error, sourceEvent: event }) } catch { /* listeners remain isolated */ }
+          }
+        }
+      }
+    }
+  }
+
+  async _archiveMessages(messages) {
+    for (const message of messages) await this.archive.put(message)
+  }
+
+  async connect() {
+    this._assertOpen()
+    if (this.state === 'connecting' || this.state === 'open') return this
+    this.state = 'connecting'
+    this._emitSafely('client.state', { state: this.state, engine: this.engine })
+    try {
+      await this.backend.connect()
+      // Do not infer authentication from a resolved connect() call. Only a backend
+      // connection.update event may mark the unified facade as open.
+      this._emitSafely('client.state', { state: this.state, engine: this.engine })
+      return this
+    } catch (error) {
+      this.state = 'close'
+      this._emitSafely('client.state', { state: this.state, engine: this.engine, error })
+      throw error
+    }
+  }
+
+  async sendMessage(jid, content, options) {
+    this._assertOpen()
+    assertJid(jid)
+    assertMessageContent(content)
+    if (this.state !== 'open') {
+      throw new Error(`client belum open (state=${this.state}); panggil connect() dulu`)
+    }
+    return this.backend.sendMessage(jid, content, options)
+  }
+
+  async sendText(jid, text, options) {
+    if (typeof text !== 'string' || !text.trim()) throw new TypeError('text harus string non-kosong')
+    return this.sendMessage(jid, { text }, options)
+  }
+
+  async sendImage(jid, image, options = {}) {
+    requireMedia(image, 'image')
+    return this.sendMessage(jid, { image, ...assertOptions(options) })
+  }
+
+  async sendVideo(jid, video, options = {}) {
+    requireMedia(video, 'video')
+    return this.sendMessage(jid, { video, ...assertOptions(options) })
+  }
+
+  async sendAudio(jid, audio, options = {}) {
+    requireMedia(audio, 'audio')
+    return this.sendMessage(jid, { audio, ...assertOptions(options) })
+  }
+
+  async sendDocument(jid, document, options = {}) {
+    requireMedia(document, 'document')
+    return this.sendMessage(jid, { document, ...assertOptions(options) })
+  }
+
+  async sendSticker(jid, sticker, options = {}) {
+    requireMedia(sticker, 'sticker')
+    return this.sendMessage(jid, { sticker, ...assertOptions(options) })
+  }
+
+  async sendLocation(jid, { latitude, longitude, name, address } = {}, options = {}) {
+    if (!Number.isFinite(latitude) || !Number.isFinite(longitude) || latitude < -90 || latitude > 90 || longitude < -180 || longitude > 180) {
+      throw new TypeError('latitude/longitude tidak valid')
+    }
+    return this.sendMessage(jid, {
+      location: {
+        degreesLatitude: latitude,
+        degreesLongitude: longitude,
+        ...(name == null ? {} : { name: String(name) }),
+        ...(address == null ? {} : { address: String(address) })
+      }, ...assertOptions(options)
+    })
+  }
+
+  async sendContact(jid, { displayName, vcard } = {}, options = {}) {
+    if (typeof displayName !== 'string' || !displayName.trim()) throw new TypeError('displayName wajib diisi')
+    if (typeof vcard !== 'string' || !vcard.includes('BEGIN:VCARD') || !vcard.includes('END:VCARD')) throw new TypeError('vcard harus berisi BEGIN:VCARD dan END:VCARD')
+    return this.sendMessage(jid, {
+      contacts: { displayName, contacts: [{ displayName, vcard }] }, ...assertOptions(options)
+    })
+  }
+
+  async sendPoll(jid, { name, values, selectableCount = 1 } = {}, options = {}) {
+    if (typeof name !== 'string' || !name.trim()) throw new TypeError('name polling wajib diisi')
+    if (!Array.isArray(values) || values.length < 2 || values.length > 12 || values.some((v) => typeof v !== 'string' || !v.trim())) {
+      throw new TypeError('values polling harus 2–12 opsi berupa string non-kosong')
+    }
+    if (!Number.isSafeInteger(selectableCount) || selectableCount < 0 || selectableCount > values.length) throw new RangeError('selectableCount tidak valid')
+    return this.sendMessage(jid, { poll: { name, values, selectableCount }, ...assertOptions(options) })
+  }
+
+  async react(jid, key, text) {
+    assertMessageKey(key)
+    if (typeof text !== 'string') throw new TypeError('reaction harus string')
+    return this.sendMessage(jid, { react: { text, key } })
+  }
+
+  async editMessage(jid, key, text) {
+    assertMessageKey(key)
+    if (typeof text !== 'string' || !text.trim()) throw new TypeError('text edit tidak boleh kosong')
+    return this.sendMessage(jid, { text, edit: key })
+  }
+
+  async deleteMessage(jid, key) {
+    assertMessageKey(key)
+    return this.sendMessage(jid, { delete: key })
+  }
+
+  async requestPairingCode(phoneNumber) {
+    this._assertOpen()
+    if (typeof this.backend.requestPairingCode !== 'function') throw new BackendNotSupportedError(this.engine, 'requestPairingCode')
+    return this.backend.requestPairingCode(phoneNumber)
+  }
+
+  async downloadMedia(message, options) {
+    this._assertOpen()
+    if (typeof this.backend.downloadMedia !== 'function') throw new BackendNotSupportedError(this.engine, 'downloadMedia')
+    return this.backend.downloadMedia(message, options)
+  }
+
+  async invoke(method, ...args) {
+    this._assertOpen()
+    if (typeof this.backend.invoke !== 'function') throw new BackendNotSupportedError(this.engine, method)
+    return this.backend.invoke(method, ...args)
+  }
+
+  capabilities() {
+    return typeof this.backend.capabilities === 'function'
+      ? this.backend.capabilities()
+      : { engine: this.engine, live: false, messaging: true, media: false, groups: false, historySync: false }
+  }
+
+  async close() {
+    if (this._closed) return
+    this._closed = true
+    this.state = 'closing'
+    for (const off of this._unsubs.splice(0)) {
+      try { off() } catch { /* best effort */ }
+    }
+    try { await this.backend.close() } finally {
+      this.state = 'closed'
+      this._emitSafely('client.state', { state: this.state, engine: this.engine })
+      this.removeAllListeners()
+    }
+  }
+
+  _assertOpen() { if (this._closed) throw new Error('KersioClient sudah ditutup') }
+}
+
+async function createKersioClient(options = {}) {
+  const sessionId = options.sessionId || 'default'
+  let backend = options.backend
+  if (!backend) {
+    switch (options.engine) {
+      case 'zapo':
+      case 'zapo-js': {
+        const { client } = options
+        if (client) backend = new ZapoBackend(client, { sessionId })
+        else {
+          let mod
+          try { mod = await import('zapo-js') } catch (error) { throw dependencyError('zapo-js', error) }
+          const clientFactory = options.clientFactory
+          if (typeof clientFactory === 'function') {
+            const zapoClient = await clientFactory(mod, options)
+            backend = new ZapoBackend(zapoClient, { sessionId })
+          } else {
+            const store = options.store || (typeof options.storeFactory === 'function' ? await options.storeFactory(mod, options) : null)
+            if (!store) throw new TypeError("engine 'zapo' perlu options.client atau options.store/storeFactory; Kersio tidak menebak konfigurasi provider penyimpanan kredensial")
+            const WaClient = mod.WaClient
+            if (typeof WaClient !== 'function') throw new TypeError("versi zapo-js ini tidak mengekspor 'WaClient'")
+            const logger = options.logger || (typeof mod.ConsoleLogger === 'function' ? new mod.ConsoleLogger(options.logLevel || 'info') : undefined)
+            const args = [{ store, sessionId }, logger].filter((v) => v !== undefined)
+            const client = new WaClient(...args)
+            backend = new ZapoBackend(client, { sessionId })
+          }
+        }
+        break
+      }
+      case 'baileys':
+        backend = await BaileysBackend.create(options)
+        break
+      case 'whatsmeow':
+      case 'whatsmeow-go':
+        backend = new WhatsmeowProcessBackend({ ...options.bridge, sessionId })
+        break
+      case 'native':
+        throw new Error('engine native hanya menyediakan transport/protokol tingkat rendah di v0.6.0-dev; pairing kriptografis, Signal dan message engine native belum complete. Pilih engine zapo, baileys, atau whatsmeow dengan bridge yang kompatibel untuk fitur pesan live.')
+      default:
+        throw new TypeError("options.engine wajib salah satu: 'zapo', 'baileys', 'whatsmeow', atau berikan options.backend")
+    }
+  }
+  return new KersioClient(backend, { sessionId, archive: options.archive || null })
+}
+
+function requireMedia(value, type) {
+  if (value === undefined || value === null || value === '') throw new TypeError(`${type} wajib diisi`)
+  if (typeof value === 'object' && !Buffer.isBuffer(value) && !(value instanceof Uint8Array) && !('url' in value) && !('stream' in value) && !('path' in value)) {
+    throw new TypeError(`${type} harus Buffer, Uint8Array, URL/path/stream, atau input yang didukung backend`)
+  }
+}
+
+function assertOptions(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('options harus objek')
+  const copy = { ...value }
+  for (const forbidden of ['image', 'video', 'audio', 'document', 'sticker', 'location', 'contacts', 'poll', 'react', 'edit', 'delete']) {
+    if (Object.hasOwn(copy, forbidden)) throw new TypeError(`jangan isi options.${forbidden}; gunakan parameter konten khusus`)
+  }
+  return copy
+}
+
+function assertMessageKey(key) {
+  if (!key || typeof key !== 'object' || typeof key.id !== 'string' || !key.id) throw new TypeError('message key harus objek dengan id non-kosong')
+}
+
+function dependencyError(pkg, cause) {
+  const error = new Error(`Backend '${pkg}' belum terpasang. Instal '${pkg}' atau pass instance client yang sudah dibuat.`)
+  error.code = 'ERR_OPTIONAL_DEPENDENCY_MISSING'
+  error.cause = cause
+  return error
+}
+
+module.exports = { KersioClient, createKersioClient, EVENT_FORWARD }

package/src/client/session-manager.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const { createKersioClient } = require('./kersio-client')
+
+class KersioSessionManager {
+  constructor({ clientFactory = createKersioClient } = {}) {
+    if (typeof clientFactory !== 'function') throw new TypeError('clientFactory harus function')
+    this.clientFactory = clientFactory
+    this.sessions = new Map()
+    this.opening = new Map()
+    this.closed = false
+  }
+
+  async open(sessionId, options = {}) {
+    assertSessionId(sessionId)
+    if (this.closed) throw new Error('KersioSessionManager sudah ditutup')
+    if (this.sessions.has(sessionId)) throw new Error(`session '${sessionId}' sudah dibuka`)
+    if (this.opening.has(sessionId)) return this.opening.get(sessionId)
+    const operation = (async () => {
+      const client = await this.clientFactory({ ...options, sessionId })
+      if (this.closed) { await client.close(); throw new Error('manager ditutup saat session dibuka') }
+      this.sessions.set(sessionId, client)
+      if (options.autoConnect !== false) {
+        try { await client.connect() } catch (error) { this.sessions.delete(sessionId); await client.close().catch(() => {}); throw error }
+      }
+      return client
+    })()
+    this.opening.set(sessionId, operation)
+    try { return await operation } finally { if (this.opening.get(sessionId) === operation) this.opening.delete(sessionId) }
+  }
+
+  get(sessionId) { return this.sessions.get(sessionId) }
+
+  async close(sessionId) {
+    const opening = this.opening.get(sessionId)
+    if (opening) { try { await opening } catch { /* no live session to close */ } }
+    const client = this.sessions.get(sessionId)
+    if (!client) return false
+    this.sessions.delete(sessionId)
+    await client.close()
+    return true
+  }
+
+  async closeAll() {
+    this.closed = true
+    await Promise.allSettled([...this.sessions.keys()].map((id) => this.close(id)))
+    await Promise.allSettled([...this.opening.values()])
+    this.sessions.clear()
+    this.opening.clear()
+  }
+
+  list() {
+    return [...this.sessions.entries()].map(([sessionId, client]) => ({ sessionId, engine: client.engine, state: client.state }))
+  }
+
+  stats() {
+    const sessions = this.list()
+    return { total: sessions.length, connecting: sessions.filter((x) => x.state === 'connecting').length, open: sessions.filter((x) => x.state === 'open').length, closed: this.closed, sessions }
+  }
+}
+
+function createKersioSessionManager(options) { return new KersioSessionManager(options) }
+function assertSessionId(id) {
+  if (typeof id !== 'string' || !id.trim() || id.length > 128 || /[\0\r\n]/.test(id)) throw new TypeError('sessionId harus string non-kosong maksimal 128 karakter')
+}
+
+module.exports = { KersioSessionManager, createKersioSessionManager }

package/src/index.js

@@ -0,0 +1,36 @@
+'use strict'
+const { makeSocket } = require('./socket/make')
+const { createSessionManager } = require('./session/manager')
+const { MemoryStore, FileStore, SQLiteStore, RedisStore, MongoStore } = require('./session/stores')
+const { EncryptedStore, ENCRYPTED_STORE_FORMAT } = require('./session/encrypted-store')
+const { LRUCache } = require('./utils/lru')
+const { generateKeyPair } = require('./utils/crypto')
+const { encodeClientPayload, PLATFORM, RELEASE_CHANNEL, WEB_SUB_PLATFORM, CONNECT_REASON, CONNECT_TYPE, PRODUCT, DEVICE_TYPE, IOS_APP_EXTENSION, TRAFFIC_ANONYMIZATION, ACCOUNT_TYPE } = require('./proto/client-payload')
+const { PLATFORM_TYPE, encodeDeviceProps, encodeHistorySyncConfig, encodeBigEndianUnsigned, buildAppVersionHash, createDevicePairingData } = require('./proto/device-props')
+const { PairingLifecycle } = require('./pairing/lifecycle')
+const { encodeBinaryNode, decodeBinaryNode, makeTokenTables, loadTokenTable, TAGS } = require('./wabinary/codec')
+const { buildPairingQrPayload, extractPairingRefs, LINKED_DEVICES_PREFIX } = require('./pairing/qr')
+const { attachQrPairingAdapter } = require('./pairing/adapter')
+const { NodeProtocol, QueryTimeoutError, RemoteIQError } = require('./protocol/node-protocol')
+const { KersioClient, createKersioClient } = require('./client/kersio-client')
+const { ZapoBackend } = require('./backends/zapo')
+const { BaileysBackend } = require('./backends/baileys')
+const { WhatsmeowProcessBackend, jsonSafe: bridgeJsonSafe } = require('./backends/whatsmeow-process')
+const { BackendNotSupportedError } = require('./backends/base')
+const { KeyedMutex, FileLockManager, LockedStore, MessageArchive, LockTimeoutError } = require('./session/locking')
+const { commitVerifiedPairSuccess } = require('./pairing/verified-commit')
+const { KersioSessionManager, createKersioSessionManager } = require('./client/session-manager')
+
+module.exports = {
+  makeSocket, createSessionManager,
+  MemoryStore, FileStore, SQLiteStore, RedisStore, MongoStore, EncryptedStore, ENCRYPTED_STORE_FORMAT,
+  LRUCache, generateKeyPair, encodeClientPayload, PairingLifecycle,
+  PLATFORM, RELEASE_CHANNEL, WEB_SUB_PLATFORM, CONNECT_REASON, CONNECT_TYPE, PRODUCT, DEVICE_TYPE, IOS_APP_EXTENSION, TRAFFIC_ANONYMIZATION, ACCOUNT_TYPE,
+  PLATFORM_TYPE, encodeDeviceProps, encodeHistorySyncConfig, encodeBigEndianUnsigned, buildAppVersionHash, createDevicePairingData,
+  encodeBinaryNode, decodeBinaryNode, makeTokenTables, loadTokenTable, WABINARY_TAGS: TAGS,
+  buildPairingQrPayload, extractPairingRefs, LINKED_DEVICES_PREFIX, attachQrPairingAdapter,
+  NodeProtocol, QueryTimeoutError, RemoteIQError,
+  KersioClient, createKersioClient, ZapoBackend, BaileysBackend, WhatsmeowProcessBackend, bridgeJsonSafe,
+  BackendNotSupportedError, KeyedMutex, FileLockManager, LockedStore, MessageArchive, LockTimeoutError,
+  commitVerifiedPairSuccess, KersioSessionManager, createKersioSessionManager
+}

package/src/pairing/adapter.js

@@ -0,0 +1,115 @@
+'use strict'
+
+const { buildPairingQrPayload, extractPairingRefs } = require('./qr')
+
+/**
+ * Optional WABinary QR adapter. It responds to a server pair-device IQ and emits
+ * payload strings only when caller-supplied account key material is complete.
+ * It does not validate pair-success signatures or mark an account authenticated.
+ */
+function attachQrPairingAdapter(sock, options = {}) {
+  if (!sock || !sock.ev || !sock.protocol || !sock.pairing) {
+    throw new TypeError('attachQrPairingAdapter memerlukan socket dengan nodeProtocol aktif')
+  }
+  const firstQrMs = options.firstQrMs ?? 60000
+  const nextQrMs = options.nextQrMs ?? 20000
+  if (!Number.isSafeInteger(firstQrMs) || firstQrMs < 1 || !Number.isSafeInteger(nextQrMs) || nextQrMs < 1) {
+    throw new TypeError('firstQrMs dan nextQrMs harus integer positif')
+  }
+  let timer = null
+  let detached = false
+
+  const clearTimer = () => { if (timer) clearTimeout(timer); timer = null }
+  const fail = (error) => {
+    clearTimer()
+    sock.pairing.fail(error)
+    sock.ev._safeEmit('pairing.adapter.error', error)
+  }
+
+  const onNode = async (node) => {
+    if (detached || !node || node.tag !== 'iq') return
+    const children = Array.isArray(node.content) ? node.content : []
+    const pairDevice = children.find((child) => child && child.tag === 'pair-device')
+    const pairSuccess = children.find((child) => child && child.tag === 'pair-success')
+
+    if (pairSuccess) {
+      clearTimer()
+      // Deliberately a candidate event: callers must verify all key/signature/HMAC
+      // material before persisting credentials or calling PairingLifecycle.complete().
+      sock.ev._safeEmit('pairing.success.candidate', { sessionId: sock.sessionId, node })
+      return
+    }
+    if (!pairDevice || node.attrs?.type !== 'set') return
+
+    const id = node.attrs?.id
+    const from = node.attrs?.from
+    if (typeof id !== 'string' || !id || typeof from !== 'string' || !from) {
+      fail(new Error('node pair-device tidak memiliki attrs id/from yang valid'))
+      return
+    }
+
+    try {
+      // Match the observed protocol request/response exchange: acknowledge the IQ first.
+      sock.sendNode({ tag: 'iq', attrs: { to: 's.whatsapp.net', type: 'result', id } })
+    } catch (error) {
+      fail(error)
+      return
+    }
+
+    if (sock.pairing.state !== 'waiting-qr') {
+      fail(new Error("pair-device diterima saat lifecycle bukan 'waiting-qr'; panggil sock.pairing.begin('qr') terlebih dahulu"))
+      return
+    }
+
+    let creds
+    try { creds = typeof options.credentials === 'function' ? await options.credentials() : options.credentials } catch (error) {
+      fail(error)
+      return
+    }
+    const refs = extractPairingRefs(node)
+    if (!refs.length) {
+      fail(new Error('pair-device tidak berisi ref biner'))
+      return
+    }
+    try {
+      const noisePublicKey = creds?.noiseKey?.public
+      const identityPublicKey = creds?.signedIdentityKey?.public || creds?.identityKey?.public
+      const advSecretKey = creds?.advSecretKey
+      // buildPairingQrPayload validates the key widths and clientType; no dummy keys are generated here.
+      const payloads = refs.map((ref) => buildPairingQrPayload({
+        ref, noisePublicKey, identityPublicKey, advSecretKey, clientType: options.clientType
+      }))
+      clearTimer()
+      let index = 0
+      const emitNext = () => {
+        if (detached || sock.pairing.state !== 'waiting-qr') return
+        if (index >= payloads.length) {
+          fail(new Error('ref QR habis sebelum pairing selesai; perlu koneksi/permintaan pairing baru'))
+          return
+        }
+        const expiresInMs = index === 0 ? firstQrMs : nextQrMs
+        sock.pairing.acceptQr(payloads[index], { index, total: payloads.length, expiresInMs })
+        index++
+        timer = setTimeout(emitNext, expiresInMs)
+      }
+      emitNext()
+    } catch (error) {
+      fail(error)
+    }
+  }
+
+  const onConnectionUpdate = ({ connection }) => {
+    if (connection === 'close') clearTimer()
+  }
+  sock.ev.on('node', onNode)
+  sock.ev.on('connection.update', onConnectionUpdate)
+
+  return function detach() {
+    detached = true
+    clearTimer()
+    sock.ev.off('node', onNode)
+    sock.ev.off('connection.update', onConnectionUpdate)
+  }
+}
+
+module.exports = { attachQrPairingAdapter }

package/src/pairing/lifecycle.js

@@ -0,0 +1,120 @@
+'use strict'
+const { EventEmitter } = require('node:events')
+
+/**
+ * Local pairing lifecycle/state machine.
+ *
+ * This class isolates pairing state and events per session. The optional WABinary
+ * QR adapter feeds observed QR candidates into this lifecycle, but success must
+ * only be finalized by a caller after full cryptographic verification.
+ */
+class PairingLifecycle extends EventEmitter {
+  constructor({ sessionId = 'default' } = {}) {
+    super()
+    this.sessionId = sessionId
+    this.state = 'idle'
+    this.method = null
+    this.startedAt = 0
+    this.completedAt = 0
+  }
+
+  begin(method) {
+    if (!['qr', 'code'].includes(method)) throw new TypeError("metode pairing harus 'qr' atau 'code'")
+    if (this.state === 'waiting-qr' || this.state === 'waiting-code') throw new Error('pairing sedang berlangsung')
+    if (this.state === 'closed') throw new Error('pairing lifecycle sudah ditutup')
+    this.method = method
+    this.state = method === 'qr' ? 'waiting-qr' : 'waiting-code'
+    this.startedAt = Date.now()
+    this.completedAt = 0
+    this._emitUpdate()
+    return this
+  }
+
+  acceptQr(qrPayload, metadata = {}) {
+    if (this.state !== 'waiting-qr') throw new Error('QR tidak diharapkan pada state sekarang')
+    if (typeof qrPayload !== 'string' || qrPayload.length === 0) throw new TypeError('qrPayload harus string non-kosong')
+    this._safeEmit('pairing.qr', { sessionId: this.sessionId, qr: qrPayload, ...metadata })
+    return this
+  }
+
+  acceptCode(code, metadata = {}) {
+    if (this.state !== 'waiting-code') throw new Error('kode tidak diharapkan pada state sekarang')
+    if (typeof code !== 'string' || !/^[A-Z0-9-]{4,16}$/i.test(code)) throw new TypeError('kode pairing memiliki format tidak valid')
+    this._safeEmit('pairing.code', { sessionId: this.sessionId, code, ...metadata })
+    return this
+  }
+
+  complete(credentials) {
+    if (!['waiting-qr', 'waiting-code'].includes(this.state)) throw new Error('pairing tidak sedang menunggu konfirmasi')
+    if (!credentials || typeof credentials !== 'object') throw new TypeError('credentials hasil pairing wajib berupa objek')
+    this.state = 'paired'
+    this.completedAt = Date.now()
+    this._emitUpdate()
+    this._safeEmit('pairing.success', { sessionId: this.sessionId, credentials })
+    return this
+  }
+
+  fail(error) {
+    if (this.state === 'closed') return this
+    const normalized = error instanceof Error ? error : new Error(String(error || 'pairing gagal'))
+    this.state = 'failed'
+    this._emitUpdate({ error: normalized.message })
+    this._safeEmit('pairing.error', { sessionId: this.sessionId, error: normalized })
+    return this
+  }
+
+  reset() {
+    if (this.state === 'closed') throw new Error('pairing lifecycle sudah ditutup')
+    this.state = 'idle'
+    this.method = null
+    this.startedAt = 0
+    this.completedAt = 0
+    this._emitUpdate()
+    return this
+  }
+
+  close() {
+    if (this.state === 'closed') return this
+    this.state = 'closed'
+    this._emitUpdate()
+    this.removeAllListeners()
+    return this
+  }
+
+
+  _safeEmit(event, ...args) {
+    for (const listener of this.rawListeners(event)) {
+      try {
+        const result = Reflect.apply(listener, this, args)
+        if (result && typeof result.then === 'function') {
+          Promise.resolve(result).catch((error) => this._reportListenerError(error, event))
+        }
+      } catch (error) {
+        this._reportListenerError(error, event)
+      }
+    }
+  }
+
+  _reportListenerError(error, sourceEvent) {
+    if (sourceEvent === 'pairing.handler.error') return
+    const normalized = error instanceof Error ? error : new Error(String(error))
+    for (const listener of this.rawListeners('pairing.handler.error')) {
+      try { Reflect.apply(listener, this, [normalized, sourceEvent]) } catch { /* never break pairing state transitions */ }
+    }
+  }
+
+  stats() {
+    return {
+      sessionId: this.sessionId,
+      state: this.state,
+      method: this.method,
+      elapsedMs: this.startedAt ? (this.completedAt || Date.now()) - this.startedAt : 0
+    }
+  }
+
+  _emitUpdate(extra = {}) {
+    this._safeEmit('pairing.update', { ...this.stats(), ...extra })
+  }
+}
+
+module.exports = { PairingLifecycle }