@zervonex/baileys 0.0.0-stage → 3.0.2

package/lib/Utils/event-buffer.js

@@ -0,0 +1,273 @@
+import EventEmitter from 'events'
+import { WAMessageStatus } from '../Types/index.js'
+import { trimUndefined } from './generics.js'
+import { updateMessageWithReaction, updateMessageWithReceipt } from './messages.js'
+import { isRealMessage, shouldIncrementChatUnread } from './process-message.js'
+
+const BUFFERABLE_EVENT = ['messaging-history.set', 'chats.upsert', 'chats.update', 'chats.delete', 'contacts.upsert', 'contacts.update', 'messages.upsert', 'messages.update', 'messages.delete', 'messages.reaction', 'message-receipt.update', 'groups.update']
+const BUFFERABLE_EVENT_SET = new Set(BUFFERABLE_EVENT)
+
+const BUFFER_TIMEOUT_MS = 30000
+const MAX_HISTORY_CACHE_SIZE = 10000
+
+const makeBufferData = () => ({
+  historySets: { chats: {}, messages: {}, contacts: {}, isLatest: false, empty: true },
+  chatUpserts: {}, chatUpdates: {}, chatDeletes: new Set(),
+  contactUpserts: {}, contactUpdates: {},
+  messageUpserts: {}, messageUpdates: {}, messageReactions: {}, messageDeletes: {}, messageReceipts: {},
+  groupUpdates: {}
+})
+
+const stringifyMessageKey = key => `${key.remoteJid},${key.id},${key.fromMe ? '1' : '0'}`
+
+export const makeEventBuffer = logger => {
+  const ev = new EventEmitter()
+  const historyCache = new Set()
+  let data = makeBufferData()
+  let isBuffering = false
+  let bufferTimeout = null
+  let bufferCount = 0
+
+  ev.on('event', map => { for (const event in map) ev.emit(event, map[event]) })
+
+  function buffer() {
+    bufferCount++
+    if (isBuffering) return
+    logger.debug('Event buffer activated')
+    isBuffering = true
+    if (bufferTimeout) clearTimeout(bufferTimeout)
+    bufferTimeout = setTimeout(() => { if (isBuffering) { logger.warn('Buffer timeout reached, auto-flushing'); flush() } }, BUFFER_TIMEOUT_MS)
+  }
+
+  function flush() {
+    if (!isBuffering) return false
+    logger.debug({ bufferCount }, 'Flushing event buffer')
+    isBuffering = false
+    bufferCount = 0
+    if (bufferTimeout) { clearTimeout(bufferTimeout); bufferTimeout = null }
+    if (historyCache.size > MAX_HISTORY_CACHE_SIZE) { logger.debug({ cacheSize: historyCache.size }, 'Clearing history cache'); historyCache.clear() }
+    const newData = makeBufferData()
+    for (const update of Object.values(data.chatUpdates)) {
+      if (update.conditional) { newData.chatUpdates[update.id] = update; delete data.chatUpdates[update.id] }
+    }
+    const consolidated = consolidateEvents(data)
+    if (Object.keys(consolidated).length) ev.emit('event', consolidated)
+    data = newData
+    logger.trace({ conditionalChatUpdatesLeft: Object.keys(newData.chatUpdates).length }, 'released buffered events')
+    return true
+  }
+
+  return {
+    process(handler) {
+      ev.on('event', handler)
+      return () => ev.off('event', handler)
+    },
+    emit(event, evData) {
+      if (isBuffering && BUFFERABLE_EVENT_SET.has(event)) { append(data, historyCache, event, evData, logger); return true }
+      return ev.emit('event', { [event]: evData })
+    },
+    isBuffering: () => isBuffering,
+    buffer,
+    flush,
+    createBufferedFunction(work) {
+      return async (...args) => {
+        buffer()
+        try {
+          const result = await work(...args)
+          if (bufferCount === 1) setTimeout(() => { if (isBuffering && bufferCount === 1) flush() }, 100)
+          return result
+        } finally {
+          bufferCount = Math.max(0, bufferCount - 1)
+          if (bufferCount === 0) setTimeout(flush, 100)
+        }
+      }
+    },
+    on: (...args) => ev.on(...args),
+    off: (...args) => ev.off(...args),
+    listener: eventName => ev.listenerCount(eventName),
+    removeAllListeners: (...args) => ev.removeAllListeners(...args)
+  }
+}
+
+function append(data, historyCache, event, eventData, logger) {
+  function absorbingChatUpdate(existing) {
+    const chatId = existing.id || ''
+    const update = data.chatUpdates[chatId]
+    if (!update) return
+    const conditionMatches = update.conditional ? update.conditional(data) : true
+    if (conditionMatches) { delete update.conditional; logger.debug({ chatId }, 'absorbed chat update in existing chat'); Object.assign(existing, concatChats(update, existing)); delete data.chatUpdates[chatId] }
+    else if (conditionMatches === false) { logger.debug({ chatId }, 'chat update condition fail, removing'); delete data.chatUpdates[chatId] }
+  }
+
+  function decrementChatReadCounterIfMsgDidUnread(message) {
+    const chatId = message.key.remoteJid
+    const chat = data.chatUpdates[chatId] || data.chatUpserts[chatId]
+    if (isRealMessage(message) && shouldIncrementChatUnread(message) && typeof chat?.unreadCount === 'number' && chat.unreadCount > 0) {
+      logger.debug({ chatId: chat.id }, 'decrementing chat counter')
+      chat.unreadCount -= 1
+      if (chat.unreadCount === 0) delete chat.unreadCount
+    }
+  }
+
+  switch (event) {
+    case 'messaging-history.set':
+      for (const chat of eventData.chats) {
+        const id = chat.id || ''
+        const existing = data.historySets.chats[id]
+        if (existing) existing.endOfHistoryTransferType = chat.endOfHistoryTransferType
+        else if (!historyCache.has(id)) { data.historySets.chats[id] = chat; historyCache.add(id); absorbingChatUpdate(chat) }
+      }
+      for (const contact of eventData.contacts) {
+        const existing = data.historySets.contacts[contact.id]
+        if (existing) Object.assign(existing, trimUndefined(contact))
+        else {
+          const hid = `c:${contact.id}`
+          if (!historyCache.has(hid) || contact.notify || contact.name || contact.verifiedName) { data.historySets.contacts[contact.id] = contact; historyCache.add(hid) }
+        }
+      }
+      for (const message of eventData.messages) {
+        const key = stringifyMessageKey(message.key)
+        if (!data.historySets.messages[key] && !historyCache.has(key)) { data.historySets.messages[key] = message; historyCache.add(key) }
+      }
+      data.historySets.empty = false
+      data.historySets.syncType = eventData.syncType
+      data.historySets.progress = eventData.progress
+      data.historySets.peerDataRequestSessionId = eventData.peerDataRequestSessionId
+      data.historySets.isLatest = eventData.isLatest || data.historySets.isLatest
+      break
+    case 'chats.upsert':
+      for (const chat of eventData) {
+        const id = chat.id || ''
+        let upsert = data.chatUpserts[id]
+        if (id && !upsert) { upsert = data.historySets.chats[id]; if (upsert) logger.debug({ chatId: id }, 'absorbed chat upsert in chat set') }
+        upsert = upsert ? concatChats(upsert, chat) : chat
+        data.chatUpserts[id] = upsert
+        absorbingChatUpdate(upsert)
+        data.chatDeletes.delete(id)
+      }
+      break
+    case 'chats.update':
+      for (const update of eventData) {
+        const chatId = update.id
+        const conditionMatches = update.conditional ? update.conditional(data) : true
+        if (conditionMatches) {
+          delete update.conditional
+          const upsert = data.historySets.chats[chatId] || data.chatUpserts[chatId]
+          if (upsert) concatChats(upsert, update)
+          else data.chatUpdates[chatId] = concatChats(data.chatUpdates[chatId] || {}, update)
+        } else if (conditionMatches === undefined) data.chatUpdates[chatId] = update
+        data.chatDeletes.delete(chatId)
+      }
+      break
+    case 'chats.delete':
+      for (const chatId of eventData) {
+        data.chatDeletes.add(chatId)
+        delete data.chatUpdates[chatId]
+        delete data.chatUpserts[chatId]
+        delete data.historySets.chats[chatId]
+      }
+      break
+    case 'contacts.upsert':
+      for (const contact of eventData) {
+        let upsert = data.contactUpserts[contact.id]
+        if (!upsert) { upsert = data.historySets.contacts[contact.id]; if (upsert) logger.debug({ contactId: contact.id }, 'absorbed contact upsert in contact set') }
+        upsert = upsert ? Object.assign(upsert, trimUndefined(contact)) : contact
+        data.contactUpserts[contact.id] = upsert
+        if (data.contactUpdates[contact.id]) { Object.assign(data.contactUpdates[contact.id], trimUndefined(contact)); delete data.contactUpdates[contact.id] }
+      }
+      break
+    case 'contacts.update':
+      for (const update of eventData) {
+        const upsert = data.historySets.contacts[update.id] || data.contactUpserts[update.id]
+        if (upsert) Object.assign(upsert, update)
+        else data.contactUpdates[update.id] = Object.assign(data.contactUpdates[update.id] || {}, update)
+      }
+      break
+    case 'messages.upsert': {
+      const { messages, type } = eventData
+      for (const message of messages) {
+        const key = stringifyMessageKey(message.key)
+        let existing = data.messageUpserts[key]?.message
+        if (!existing) { existing = data.historySets.messages[key]; if (existing) logger.debug({ messageId: key }, 'absorbed message upsert in message set') }
+        if (existing) message.messageTimestamp = existing.messageTimestamp
+        if (data.messageUpdates[key]) { logger.debug('absorbed prior message update in message upsert'); Object.assign(message, data.messageUpdates[key].update); delete data.messageUpdates[key] }
+        if (data.historySets.messages[key]) data.historySets.messages[key] = message
+        else data.messageUpserts[key] = { message, type: type === 'notify' || data.messageUpserts[key]?.type === 'notify' ? 'notify' : type }
+      }
+      break
+    }
+    case 'messages.update':
+      for (const { key, update } of eventData) {
+        const keyStr = stringifyMessageKey(key)
+        const existing = data.historySets.messages[keyStr] || data.messageUpserts[keyStr]?.message
+        if (existing) {
+          Object.assign(existing, update)
+          if (update.status === WAMessageStatus.READ && !key.fromMe) decrementChatReadCounterIfMsgDidUnread(existing)
+        } else {
+          const msgUpdate = data.messageUpdates[keyStr] || { key, update: {} }
+          Object.assign(msgUpdate.update, update)
+          data.messageUpdates[keyStr] = msgUpdate
+        }
+      }
+      break
+    case 'messages.delete':
+      if ('keys' in eventData) {
+        for (const key of eventData.keys) {
+          const keyStr = stringifyMessageKey(key)
+          if (!data.messageDeletes[keyStr]) data.messageDeletes[keyStr] = key
+          delete data.messageUpserts[keyStr]
+          delete data.messageUpdates[keyStr]
+        }
+      }
+      break
+    case 'messages.reaction':
+      for (const { key, reaction } of eventData) {
+        const keyStr = stringifyMessageKey(key)
+        const existing = data.messageUpserts[keyStr]
+        if (existing) updateMessageWithReaction(existing.message, reaction)
+        else { data.messageReactions[keyStr] = data.messageReactions[keyStr] || { key, reactions: [] }; updateMessageWithReaction(data.messageReactions[keyStr], reaction) }
+      }
+      break
+    case 'message-receipt.update':
+      for (const { key, receipt } of eventData) {
+        const keyStr = stringifyMessageKey(key)
+        const existing = data.messageUpserts[keyStr]
+        if (existing) updateMessageWithReceipt(existing.message, receipt)
+        else { data.messageReceipts[keyStr] = data.messageReceipts[keyStr] || { key, userReceipt: [] }; updateMessageWithReceipt(data.messageReceipts[keyStr], receipt) }
+      }
+      break
+    case 'groups.update':
+      for (const update of eventData) {
+        if (!data.groupUpdates[update.id]) data.groupUpdates[update.id] = Object.assign(data.groupUpdates[update.id] || {}, update)
+      }
+      break
+    default:
+      throw new Error(`"${event}" cannot be buffered`)
+  }
+}
+
+function consolidateEvents(data) {
+  const map = {}
+  const add = (key, list) => { if (list.length) map[key] = list }
+  if (!data.historySets.empty) map['messaging-history.set'] = { chats: Object.values(data.historySets.chats), messages: Object.values(data.historySets.messages), contacts: Object.values(data.historySets.contacts), syncType: data.historySets.syncType, progress: data.historySets.progress, isLatest: data.historySets.isLatest, peerDataRequestSessionId: data.historySets.peerDataRequestSessionId }
+  add('chats.upsert', Object.values(data.chatUpserts))
+  add('chats.update', Object.values(data.chatUpdates))
+  add('chats.delete', Array.from(data.chatDeletes))
+  const messageUpsertList = Object.values(data.messageUpserts)
+  if (messageUpsertList.length) map['messages.upsert'] = { messages: messageUpsertList.map(m => m.message), type: messageUpsertList[0].type }
+  add('messages.update', Object.values(data.messageUpdates))
+  const messageDeleteList = Object.values(data.messageDeletes)
+  if (messageDeleteList.length) map['messages.delete'] = { keys: messageDeleteList }
+  add('messages.reaction', Object.values(data.messageReactions).flatMap(({ key, reactions }) => reactions.map(reaction => ({ key, reaction }))))
+  add('message-receipt.update', Object.values(data.messageReceipts).flatMap(({ key, userReceipt }) => userReceipt.map(receipt => ({ key, receipt }))))
+  add('contacts.upsert', Object.values(data.contactUpserts))
+  add('contacts.update', Object.values(data.contactUpdates))
+  add('groups.update', Object.values(data.groupUpdates))
+  return map
+}
+
+function concatChats(a, b) {
+  if (b.unreadCount === null && a.unreadCount < 0) { a.unreadCount = undefined; b.unreadCount = undefined }
+  if (typeof a.unreadCount === 'number' && typeof b.unreadCount === 'number') { b = { ...b }; if (b.unreadCount >= 0) b.unreadCount = Math.max(b.unreadCount, 0) + Math.max(a.unreadCount, 0) }
+  return Object.assign(a, b)
+}

package/lib/Utils/extras.js

@@ -0,0 +1,186 @@
+import { trimUndefined } from './generics.js'
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from 'crypto'
+import { proto } from '../../WAProto/index.js'
+
+export const SCHEDULED_MSG_META_TYPE = 'scheduled_message'
+export const SCHEDULED_MSG_MAX_PER_CHAT = 30
+export const SCHEDULED_MSG_MAX_MEDIA = 1
+export const SCHEDULED_MSG_RESOURCE_LIMIT_NACK_CODE = 419
+export const SCHEDULED_MSG_REVEAL_KEY_BYTES = 32
+export const SCHEDULED_MSG_REVEAL_KEY_IV_BYTES = 12
+export const SCHEDULED_MSG_REVEAL_KEY_RETENTION_DAYS = 30
+export const SCHEDULED_MSG_TAG_BYTES = 16
+export const SCHEDULED_MSG_WINDOW = Object.freeze({ chat: { minSeconds: 600, maxSeconds: 1209600 }, newsletter: { minSeconds: 600, maxSeconds: 2592000 } })
+export const generateRevealKey = () => randomBytes(SCHEDULED_MSG_REVEAL_KEY_BYTES)
+export const generateRevealKeyId = () => randomUUID()
+export const encryptWithRevealKey = (plaintext, revealKey) => {
+    const key = Buffer.from(revealKey)
+    if (key.length !== SCHEDULED_MSG_REVEAL_KEY_BYTES) throw new TypeError(`reveal key must be ${SCHEDULED_MSG_REVEAL_KEY_BYTES} bytes`)
+    const encIv = randomBytes(SCHEDULED_MSG_REVEAL_KEY_IV_BYTES)
+    const cipher = createCipheriv('aes-256-gcm', key, encIv)
+    const body = Buffer.concat([cipher.update(Buffer.from(plaintext)), cipher.final()])
+    return { encIv, encPayload: Buffer.concat([body, cipher.getAuthTag()]) }
+}
+export const decryptWithRevealKey = (encPayload, encIv, revealKey) => {
+    const key = Buffer.from(revealKey)
+    const payload = Buffer.from(encPayload)
+    if (payload.length < SCHEDULED_MSG_TAG_BYTES) throw new TypeError('encrypted payload is too short to carry an auth tag')
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(encIv))
+    decipher.setAuthTag(payload.subarray(payload.length - SCHEDULED_MSG_TAG_BYTES))
+    return Buffer.concat([decipher.update(payload.subarray(0, payload.length - SCHEDULED_MSG_TAG_BYTES)), decipher.final()])
+}
+export const buildConditionalRevealMessage = ({ encPayload, encIv, revealKeyId }) => ({ conditionalRevealMessage: { conditionalRevealMessageType: proto.Message.ConditionalRevealMessage.ConditionalRevealMessageType.SCHEDULED_MESSAGE, encPayload: Buffer.from(encPayload), encIv: Buffer.from(encIv), revealKeyId } })
+export const encodeScheduledMessage = (message, revealKey = generateRevealKey()) => {
+    const plaintext = proto.Message.encode(proto.Message.fromObject(message)).finish()
+    const { encIv, encPayload } = encryptWithRevealKey(plaintext, revealKey)
+    const revealKeyId = generateRevealKeyId()
+    return { revealKey, revealKeyId, encIv, encPayload, message: buildConditionalRevealMessage({ encPayload, encIv, revealKeyId }) }
+}
+export const decodeScheduledMessage = (conditionalRevealMessage, revealKey) => {
+    const inner = conditionalRevealMessage?.conditionalRevealMessage ?? conditionalRevealMessage
+    if (!inner?.encPayload || !inner?.encIv) throw new TypeError('conditionalRevealMessage is missing encPayload or encIv')
+    return proto.Message.decode(decryptWithRevealKey(inner.encPayload, inner.encIv, revealKey))
+}
+export const buildScheduledMsgMetaNode = ({ kind = 'schedule', scheduledTimestampS, revealKeyId, revealKey }) => {
+    if (!revealKeyId) throw new TypeError('revealKeyId is required')
+    if (kind === 'schedule' && !revealKey) throw new TypeError('scheduling requires the reveal key')
+    const attrs = { type: SCHEDULED_MSG_META_TYPE }
+    if (kind === 'schedule') {
+        if (!Number.isFinite(Number(scheduledTimestampS))) throw new TypeError('scheduledTimestampS must be a unix timestamp in seconds')
+        attrs.st = String(Math.floor(Number(scheduledTimestampS)))
+    }
+    return { tag: 'meta', attrs, content: [{ tag: 'key', attrs: { rkid: revealKeyId }, content: kind === 'schedule' ? Buffer.from(revealKey) : undefined }] }
+}
+export const buildUnscheduleProtocolMessage = (key) => ({ protocolMessage: { key, type: proto.Message.ProtocolMessage.Type.MESSAGE_UNSCHEDULE } })
+export const isScheduledTimeValid = (scheduledTimestampS, nowSeconds = Math.floor(Date.now() / 1000), window = SCHEDULED_MSG_WINDOW.chat) => {
+    const rounded = Math.floor(nowSeconds / 60) * 60
+    return scheduledTimestampS - rounded >= window.minSeconds && scheduledTimestampS - nowSeconds <= window.maxSeconds
+}
+export const SplitPaymentStatus = Object.freeze({ PENDING: 0, PAID: 1 })
+export const ReminderFrequency = Object.freeze({ REMINDER_FREQUENCY_UNKNOWN: 0, WEEKLY: 1, BI_WEEKLY: 2, MONTHLY: 3, QUARTERLY: 4 })
+export const ReminderStatus = Object.freeze({ REMINDER_STATUS_UNKNOWN: 0, ACTIVE: 1, CANCELLED_BY_CREATOR: 2, STOPPED_BY_RECEIVER: 3, EXPIRED: 4, PAID: 5 })
+export const MONEY_OFFSET = 1000
+const drop = (object) => { for (const key of Object.keys(object)) { if (object[key] === undefined || object[key] === null) delete object[key] } return object }
+export const money = (amount, currencyCode, offset = MONEY_OFFSET) => {
+    const value = Number(amount)
+    if (!Number.isFinite(value) || value < 0) throw new TypeError('money needs a non-negative amount')
+    if (typeof currencyCode !== 'string' || currencyCode.length !== 3) throw new TypeError('money needs a three letter currency code, like IDR or USD')
+    if (!Number.isInteger(offset) || offset <= 0) throw new TypeError('money offset must be a positive integer')
+    return { value: Math.round(value * offset), offset, currencyCode: currencyCode.toUpperCase() }
+}
+export const readMoney = (value) => { if (!value?.offset) return undefined; return { amount: Number(value.value) / Number(value.offset), currencyCode: value.currencyCode } }
+export const buildSplitPayment = ({ splitId, total, currency, description, requesterJid, participants = [], createdAt } = {}) => {
+    if (!splitId) throw new TypeError('buildSplitPayment needs a splitId')
+    if (!participants.length) throw new TypeError('buildSplitPayment needs at least one participant')
+    return drop({ splitId: String(splitId), totalAmount: total === undefined ? undefined : money(total, currency), description, requesterJid, participants: participants.map((p, i) => { if (!p?.jid) throw new TypeError(`participant ${i} needs a jid`); return drop({ jid: p.jid, amount: p.amount === undefined ? undefined : money(p.amount, p.currency ?? currency), status: p.status ?? SplitPaymentStatus.PENDING }) }), createdAtMs: createdAt === undefined ? Date.now() : Number(createdAt) })
+}
+export const buildSplitPaymentUpdate = ({ splitId, participantJid } = {}) => { if (!splitId || !participantJid) throw new TypeError('buildSplitPaymentUpdate needs both splitId and participantJid'); return { splitId: String(splitId), participantJid } }
+export const buildPaymentReminder = ({ reminderId, instanceId, description, frequency = ReminderFrequency.MONTHLY, status = ReminderStatus.ACTIVE, amount, currency, payeeVpa, payeeJid, payerJid } = {}) => {
+    if (!reminderId) throw new TypeError('buildPaymentReminder needs a reminderId')
+    return drop({ reminderId: String(reminderId), instanceId: instanceId === undefined ? undefined : String(instanceId), description, frequency, status, amount: amount === undefined ? undefined : money(amount, currency), payeeVpa, payeeJid, payerJid })
+}
+export const readSplitPayment = (msg) => {
+    const split = (msg?.message ?? msg)?.splitPaymentMessage
+    if (!split) return null
+    return drop({ splitId: split.splitId, total: readMoney(split.totalAmount), description: split.description, requesterJid: split.requesterJid, createdAtMs: split.createdAtMs === undefined ? undefined : Number(split.createdAtMs), participants: (split.participants ?? []).map(p => drop({ jid: p.jid, amount: readMoney(p.amount), status: p.status })) })
+}
+export const readPaymentReminder = (msg) => {
+    const reminder = (msg?.message ?? msg)?.paymentReminderMessage
+    if (!reminder) return null
+    return drop({ reminderId: reminder.reminderId, instanceId: reminder.instanceId, description: reminder.description, frequency: reminder.frequency, status: reminder.status, amount: readMoney(reminder.amount), payeeVpa: reminder.payeeVpa, payeeJid: reminder.payeeJid, payerJid: reminder.payerJid })
+}
+export const StatusLinkType = Object.freeze({ RASTERIZED_LINK_PREVIEW: 1, RASTERIZED_LINK_TRUNCATED: 2, RASTERIZED_LINK_FULL_URL: 3 })
+export const STICKER_DEFAULT_AREA = Object.freeze({ x: 0.25, y: 0.4, width: 0.5, height: 0.2 })
+const fraction = (value, name) => { const n = Number(value); if (!Number.isFinite(n) || n < 0 || n > 1) throw new TypeError(`${name} must be between 0 and 1`); return n }
+export const stickerArea = ({ x, y, width, height } = STICKER_DEFAULT_AREA) => {
+    const left = fraction(x, 'x'), top = fraction(y, 'y'), right = fraction(left + Number(width), 'x + width'), bottom = fraction(top + Number(height), 'y + height')
+    if (right <= left || bottom <= top) throw new TypeError('a sticker area needs a positive width and height')
+    return [{ x: left, y: top }, { x: right, y: top }, { x: right, y: bottom }, { x: left, y: bottom }]
+}
+const annotation = (area, fields) => ({ polygonVertices: Array.isArray(area) ? area : stickerArea(area), ...fields })
+export const locationSticker = ({ latitude, longitude, name, area, skipConfirmation } = {}) => {
+    const degreesLatitude = Number(latitude), degreesLongitude = Number(longitude)
+    if (!Number.isFinite(degreesLatitude) || !Number.isFinite(degreesLongitude)) throw new TypeError('locationSticker needs a numeric latitude and longitude')
+    return annotation(area, { location: { degreesLatitude, degreesLongitude, ...(name ? { name } : {}) }, ...(skipConfirmation === undefined ? {} : { shouldSkipConfirmation: !!skipConfirmation }) })
+}
+export const channelSticker = ({ jid, name, serverMessageId = 0, accessibilityText, area } = {}) => {
+    if (typeof jid !== 'string' || !jid.endsWith('@newsletter')) throw new TypeError('channelSticker needs the channel jid ending in @newsletter')
+    return annotation(area, { newsletter: { newsletterJid: jid, serverMessageId: Number(serverMessageId), ...(name ? { newsletterName: name } : {}), ...(accessibilityText ? { accessibilityText } : {}) } })
+}
+export const linkSticker = ({ url, title, area, linkType = StatusLinkType.RASTERIZED_LINK_PREVIEW } = {}) => {
+    if (typeof url !== 'string' || !url) throw new TypeError('linkSticker needs a url')
+    return annotation(area, { tapAction: { tapUrl: url, ...(title ? { title } : {}) }, statusLinkType: linkType })
+}
+export const musicSticker = ({ songId, title, author, mediaId, artworkDirectPath, artworkSha256, artworkEncSha256, artworkMediaKey, artistAttribution, countryBlocklist, isExplicit, startTimeMs = 0, derivedStartTimeMs, durationMs, area } = {}) => {
+    if (!songId && !mediaId) throw new TypeError('musicSticker needs at least a songId or a musicContentMediaId')
+    const bytes = v => v === undefined ? undefined : Buffer.isBuffer(v) ? v : Buffer.from(v, 'base64')
+    const em = { ...(songId ? { songId: String(songId) } : {}), ...(mediaId ? { musicContentMediaId: String(mediaId) } : {}), ...(title ? { title } : {}), ...(author ? { author } : {}), ...(artistAttribution ? { artistAttribution } : {}), ...(artworkDirectPath ? { artworkDirectPath } : {}), ...(isExplicit === undefined ? {} : { isExplicit: !!isExplicit }), musicSongStartTimeInMs: Number(startTimeMs), ...(derivedStartTimeMs === undefined ? {} : { derivedContentStartTimeInMs: Number(derivedStartTimeMs) }), ...(durationMs === undefined ? {} : { overlapDurationInMs: Number(durationMs) }) }
+    for (const [k, v] of [['artworkSha256', artworkSha256], ['artworkEncSha256', artworkEncSha256], ['artworkMediaKey', artworkMediaKey], ['countryBlocklist', countryBlocklist]]) { const b = bytes(v); if (b) em[k] = b }
+    return annotation(area, { embeddedContent: { embeddedMusic: em } })
+}
+export const messageSticker = ({ stanzaId, message, area } = {}) => {
+    if (!message) throw new TypeError('messageSticker needs the message it embeds')
+    return annotation(area, { embeddedContent: { embeddedMessage: { ...(stanzaId ? { stanzaId } : {}), message } } })
+}
+const STICKER_ACTIONS = ['location', 'newsletter', 'embeddedAction', 'tapAction']
+export const normalizeStickers = (stickers) => {
+    const list = Array.isArray(stickers) ? stickers : [stickers]
+    return list.filter(Boolean).map((sticker, i) => {
+        const v = sticker.polygonVertices
+        if (!Array.isArray(v) || v.length !== 4) throw new TypeError(`sticker ${i} needs four polygonVertices`)
+        const actions = STICKER_ACTIONS.filter(n => sticker[n] !== undefined && sticker[n] !== null)
+        if (actions.length > 1) throw new TypeError(`sticker ${i} sets ${actions.join(' and ')}, but only one action is allowed per sticker`)
+        return proto.InteractiveAnnotation.fromObject(sticker)
+    })
+}
+export const readStickers = (message) => {
+    const media = message?.imageMessage ?? message?.videoMessage ?? message
+    const annotations = media?.interactiveAnnotations
+    if (!Array.isArray(annotations) || !annotations.length) return []
+    return annotations.map(item => {
+        const [topLeft, , bottomRight] = item.polygonVertices ?? []
+        const music = item.embeddedContent?.embeddedMusic
+        return { kind: item.location ? 'location' : item.newsletter ? 'channel' : item.tapAction ? 'link' : music ? 'music' : item.embeddedContent?.embeddedMessage ? 'message' : 'unknown', area: topLeft && bottomRight ? { x: topLeft.x, y: topLeft.y, width: bottomRight.x - topLeft.x, height: bottomRight.y - topLeft.y } : undefined, location: item.location ?? undefined, channel: item.newsletter ?? undefined, link: item.tapAction ? { url: item.tapAction.tapUrl, title: item.tapAction.title, linkType: item.statusLinkType } : undefined, music: music ? { songId: music.songId, title: music.title, author: music.author } : undefined, message: item.embeddedContent?.embeddedMessage ?? undefined, annotation: item }
+    })
+}
+export const MusicMessageStyle = Object.freeze({ UNKNOWN: 0, VINYL: 1 })
+export const MUSIC_ALLOWED_HOSTS = Object.freeze(['.whatsapp.net', '.whatsapp.com', '.fbcdn.net', '.facebook.com', '.instagram.com', '.cdninstagram.com'])
+export const isMusicHostAllowed = (value) => { let host; try { host = new URL(String(value)).hostname.toLowerCase() } catch { return false } return MUSIC_ALLOWED_HOSTS.some(s => host.endsWith(s) || host === s.slice(1)) }
+const assertMusicHost = (value, label) => { if (value === undefined) return undefined; if (!isMusicHostAllowed(value)) throw new TypeError(`${label} must be hosted on ${MUSIC_ALLOWED_HOSTS.join(', ')}`); return value }
+const embeddedMusicOf = (options) => musicSticker(options).embeddedContent.embeddedMusic
+export const buildMusicMessage = ({ songUri, artworkUri, style = MusicMessageStyle.VINYL, contextInfo, ...music } = {}) => trimUndefined({ embeddedMusic: embeddedMusicOf(music), songUri: assertMusicHost(songUri, 'songUri'), artworkUri: assertMusicHost(artworkUri, 'artworkUri'), style, contextInfo })
+export const readMusicMessage = (msg) => {
+    const music = (msg?.message ?? msg)?.musicMessage
+    if (!music) return null
+    const em = music.embeddedMusic ?? {}
+    return { songId: em.songId, mediaId: em.musicContentMediaId, title: em.title, author: em.author, artistAttribution: em.artistAttribution, isExplicit: em.isExplicit, startTimeMs: em.musicSongStartTimeInMs, durationMs: em.overlapDurationInMs, songUri: music.songUri, artworkUri: music.artworkUri, style: music.style, embeddedMusic: em }
+}
+export function buildAckStanza(node, errorCode, meId) {
+    const { tag, attrs } = node
+    const stanza = { tag: 'ack', attrs: { id: attrs.id, to: attrs.from, class: tag } }
+    if (errorCode) stanza.attrs.error = errorCode.toString()
+    if (attrs.participant) stanza.attrs.participant = attrs.participant
+    if (attrs.recipient) stanza.attrs.recipient = attrs.recipient
+    if (attrs.type) stanza.attrs.type = attrs.type
+    if (tag === 'message' && meId) stanza.attrs.from = meId
+    return stanza
+}
+export const pickSenderKeyRecipients = (devices, senderKeyMap, { force = false, skip } = {}) => {
+    const recipients = []
+    for (const device of devices) {
+        const deviceJid = device?.jid
+        if (!deviceJid || (!force && senderKeyMap[deviceJid]) || (skip && skip(device))) continue
+        recipients.push(deviceJid)
+    }
+    return recipients
+}
+export const deliveredSenderKeyJids = nodes => { const delivered = new Set(); for (const node of nodes || []) { const jid = node?.attrs?.jid; if (jid) delivered.add(jid) } return delivered }
+export const senderKeyResetSummary = (stored, jid) => { const devices = Object.keys(stored?.[jid] || {}); return { jid, cleared: devices.length, devices } }
+export const commitSenderKeyDelivery = (senderKeyMap, recipients, nodes) => {
+    const delivered = deliveredSenderKeyJids(nodes), marked = [], skipped = []
+    for (const jid of recipients) { if (delivered.has(jid)) { senderKeyMap[jid] = true; marked.push(jid) } else { delete senderKeyMap[jid]; skipped.push(jid) } }
+    return { marked, skipped }
+}
+export const GROUP_ADDRESSING_MODES = Object.freeze(['pn', 'lid'])
+export const isUsableGroupMetadata = metadata => { if (!metadata || typeof metadata !== 'object') return false; if (!Array.isArray(metadata.participants)) return false; return GROUP_ADDRESSING_MODES.includes(metadata.addressingMode) }
+export const describeUnusableGroupMetadata = metadata => { if (!metadata || typeof metadata !== 'object') return 'nothing cached'; if (!Array.isArray(metadata.participants)) return 'no participants'; if (metadata.addressingMode === undefined || metadata.addressingMode === null) return 'no addressingMode'; return `addressingMode ${JSON.stringify(metadata.addressingMode)} is not pn or lid` }