refactor(events): group new payload fields after the is-flags and rename isOffline to isOld

Author: zeative

docs/content/events.mdx

@@ -298,7 +298,7 @@ client.on('message', async (msg) => {
 | `senderLid` | `string \| null` | The sender's LID (linked-device identifier), if known. Keeps the raw LID even after `senderId` is resolved to PN. |
 | `senderName` | `string \| null` | The sender's WhatsApp push name. |
 | `senderUsername` | `string \| null` | The sender's WhatsApp username (`@handle`), without the `@`. `null` unless WhatsApp sends one — mostly group messages from LID-only senders. |
-| `isOffline` | `boolean` | `true` for a backlog message replayed after a reconnect. Guard on this so the bot does not answer old messages twice. |
+| `isOld` | `boolean` | `true` for a backlog message replayed after a reconnect. Guard on this so the bot does not answer old messages twice. |
 | `forwardCount` | `number` | Forward hops. `>= 5` is WhatsApp's "forwarded many times". |
 | `ephemeralDuration` | `number \| null` | The chat's disappearing timer in seconds. |
 | `addressingMode` | `'pn' \| 'lid'` | How WhatsApp addressed the message. |

docs/content/message-payload.mdx

@@ -58,14 +58,8 @@ So plain fields are cheap to read; the function fields do real work (network/asy
 | `senderLid` | `string \| null` | `key.participantAlt` / `remoteJidAlt` ending in `@lid` | The sender's LID, when WhatsApp exposes one. `null` if not available. |
 | `senderName` | `string \| null` | `message.pushName` | Display/push name. Can be `null` or spoofed — don't use for authz. |
 | `senderUsername` | `string \| null` | `key.participantUsername` / `remoteJidUsername` | The sender's WhatsApp username (the `@handle`), without the `@`. `null` unless WhatsApp sends one — see the note below. |
-| `isOffline` | `boolean` | `messages.upsert` type `append` | **`true` for a backlog message replayed after a reconnect.** Skip these so your bot doesn't answer hours-old messages twice. |
-| `forwardCount` | `number` | `contextInfo.forwardingScore` | How many hops the message has been forwarded. `0` = not forwarded, `>= 5` = WhatsApp's "forwarded many times". |
-| `ephemeralDuration` | `number \| null` | `contextInfo.expiration` | The chat's disappearing timer **in seconds**, or `null` when messages are kept. |
-| `addressingMode` | `'pn' \| 'lid'` | `key.addressingMode` | Whether WhatsApp addressed this message by phone number or by LID. Useful when debugging identity resolution. |
-| `mentionedGroups` | `string[]` | `contextInfo.groupMentions` | JIDs of groups tagged in the message (community `@group` mentions). |
-| `ad` | `AdAttribution \| undefined` | `contextInfo.externalAdReply` | Present **only** on the first message of a chat opened from a Meta ad. |
-| `business` | `BusinessInfo \| undefined` | `verifiedBizName` | Present **only** when the sender is a verified WhatsApp Business account. |
 | `senderDevice` | `SenderDevice` | Parsed from the sender's device jid | Which client app sent it: `android` · `ios` · `web` · `desktop` · `unknown`. |
+| `addressingMode` | `'pn' \| 'lid'` | `key.addressingMode` | Whether WhatsApp addressed this message by phone number or by LID. Useful when debugging identity resolution. |
 | `isFromMe` | `boolean` | `key.fromMe === true` | `true` if your own account sent it (echo of your sends, other-device activity). |
 | `isGroup` | `boolean` | `remoteJid` is a group jid | Branch group vs DM logic. |
 | `isNewsletter` | `boolean` | `remoteJid` ends `@newsletter` | Message came from a channel/newsletter. |
@@ -82,7 +76,12 @@ So plain fields are cheap to read; the function fields do real work (network/asy
 | `text` | `string` | body / caption / poll name / location label, after unwrapping | The textual content. Empty string if none. Caption text for media is mirrored here too. |
 | `timestamp` | `number` | `messageTimestamp`, converted **seconds → milliseconds** | Unix **ms** epoch. Feed straight into `new Date(ctx.timestamp)`. `0` if invalid. |
 | `mentions` | `string[]` | `contextInfo.mentionedJid`, mapped to PN | Jids tagged in the message. |
+| `mentionedGroups` | `string[]` | `contextInfo.groupMentions` | Groups tagged in the message (community `@group` mentions). |
 | `links` | `string[]` | Regex over `text` | URLs found in the text (trailing punctuation trimmed). |
+| `forwardCount` | `number` | `contextInfo.forwardingScore` | How many hops the message has been forwarded. `0` = not forwarded, `>= 5` = WhatsApp's "forwarded many times". |
+| `ephemeralDuration` | `number \| null` | `contextInfo.expiration` | The chat's disappearing timer **in seconds**, or `null` when messages are kept. |
+| `ad` | `AdAttribution \| undefined` | `contextInfo.externalAdReply` | Present **only** on the first message of a chat opened from a Meta ad. See [`ad`](#ad--where-a-lead-came-from). |
+| `business` | `BusinessInfo \| undefined` | `verifiedBizName` | Present **only** when the sender is a verified WhatsApp Business account. |
 
 ---
 
@@ -95,6 +94,7 @@ All computed from the message **except `isSpam`** (reserved, always `false` for
 | `isViewOnce` | view-once wrapper present, or media marked `viewOnce`. |
 | `isEphemeral` | ephemeral wrapper present, or `contextInfo.expiration > 0` (disappearing messages). |
 | `isForwarded` | marked forwarded, or `forwardingScore > 0`. |
+| `isOld` | the message is **backlog** — it arrived while your bot was disconnected and WhatsApp replayed it on reconnect. Guard on this so you don't answer hours-old messages. |
 | `isQuestion` | trimmed `text` ends with `?`. |
 | `isPrefix` | `text` starts with one of your configured command **prefixes**. |
 | `isTagMe` | your jid is in `mentions` (you were @-tagged). |
@@ -299,7 +299,7 @@ A few values come from your `Client` config rather than the raw message:
 - **`roomId` follows the conversation, not the direction** — safe as a reply target for both inbound and your own (`isFromMe`) messages.
 - **`isSpam` is reserved** and always `false` today. Use `forwardCount >= 5` for chain-message detection.
 - **Answer only live messages.** After a reconnect WhatsApp replays everything you missed. Guard with
-  `if (ctx.isOffline) return` unless you deliberately want to process the backlog.
+  `if (ctx.isOld) return` unless you deliberately want to process the backlog.
 - **Mirror the disappearing timer on replies.** `ctx.reply()` does not inherit it — pass
   `ctx.ephemeralDuration` to `.disappearing()` yourself, or your answer outlives the thread it belongs to.
 - **`senderUsername` is usually `null` — WhatsApp sends the phone number _or_ the username, never

src/events/context.ts

@@ -46,15 +46,11 @@ export interface MediaAttachment {
   fileName: string | null
   fileSize: number | null
   ptt: boolean
-  /** Playback length in seconds, for audio and video. */
+  isAnimated: boolean
   duration: number | null
   width: number | null
   height: number | null
-  /** Page count, for documents. */
   pages: number | null
-  /** `true` for an animated sticker or a GIF-playback video. */
-  isAnimated: boolean
-  /** Inline JPEG preview, when WhatsApp sent one. Lets you show a thumbnail without downloading. */
   thumbnail: Buffer | null
   buffer(): Promise<Buffer>
   stream(): Promise<Readable>
@@ -248,7 +244,6 @@ export interface MessageContext {
   senderId: string
   senderLid: string | null
   senderName: string | null
-  /** WhatsApp username (the `@handle`), without the `@`. Only sent for accounts that set one. */
   senderUsername: string | null
   senderDevice: SenderDevice
   timestamp: number
@@ -262,20 +257,7 @@ export interface MessageContext {
   isViewOnce: boolean
   isEphemeral: boolean
   isForwarded: boolean
-  /** `true` for a backlog message replayed after a reconnect. Skip these to avoid answering twice. */
-  isOffline: boolean
-  /** How many hops this message has been forwarded. `>= 5` is WhatsApp's "forwarded many times". */
-  forwardCount: number
-  /** The chat's disappearing timer in seconds, or `null` when messages are kept. */
-  ephemeralDuration: number | null
-  /** Whether WhatsApp addressed this message by phone number or by LID. */
-  addressingMode: 'pn' | 'lid'
-  /** JIDs of groups tagged in the message (community `@group` mentions). */
-  mentionedGroups: string[]
-  /** Present only on the first message of a chat opened from a Meta ad. */
-  ad?: AdAttribution
-  /** Present only when the sender is a verified WhatsApp Business account. */
-  business?: BusinessInfo
+  isOld: boolean
   isQuestion: boolean
   isPrefix: boolean
   isTagMe: boolean
@@ -290,6 +272,12 @@ export interface MessageContext {
   isGroupStatusMention: boolean
   isGroupStatus: boolean
   isStory: boolean
+  forwardCount: number
+  ephemeralDuration: number | null
+  addressingMode: 'pn' | 'lid'
+  mentionedGroups: string[]
+  ad?: AdAttribution
+  business?: BusinessInfo
   roomName(): Promise<string | null>
   receiverName(): Promise<string | null>
   media?: ContextMedia
@@ -326,7 +314,7 @@ export interface BuildContextInput {
   isForwarded: boolean
   isBroadcast: boolean
   isNewsletter: boolean
-  isOffline?: boolean
+  isOld?: boolean
   forwardCount?: number
   ephemeralDuration?: number | null
   addressingMode?: 'pn' | 'lid'
@@ -510,13 +498,7 @@ export const buildMessageContext = (input: BuildContextInput): MessageContext =>
     isViewOnce: input.isViewOnce,
     isEphemeral: input.isEphemeral,
     isForwarded: input.isForwarded,
-    isOffline: input.isOffline === true,
-    forwardCount: input.forwardCount ?? 0,
-    ephemeralDuration: input.ephemeralDuration ?? null,
-    addressingMode: input.addressingMode ?? 'pn',
-    mentionedGroups: input.mentionedGroups ?? [],
-    ...(input.ad !== undefined ? { ad: input.ad } : {}),
-    ...(input.business !== undefined ? { business: input.business } : {}),
+    isOld: input.isOld === true,
     isQuestion: isQuestionOf(input.text),
     isPrefix: isPrefixOf(input.text, input.prefixes),
     isTagMe: isTagMeOf(input.selfJid, input.mentions),
@@ -531,6 +513,12 @@ export const buildMessageContext = (input: BuildContextInput): MessageContext =>
     isGroupStatusMention: flags.isGroupStatusMention,
     isGroupStatus: flags.isGroupStatus,
     isStory: remoteJid === 'status@broadcast',
+    forwardCount: input.forwardCount ?? 0,
+    ephemeralDuration: input.ephemeralDuration ?? null,
+    addressingMode: input.addressingMode ?? 'pn',
+    mentionedGroups: input.mentionedGroups ?? [],
+    ...(input.ad !== undefined ? { ad: input.ad } : {}),
+    ...(input.business !== undefined ? { business: input.business } : {}),
     roomName: input.resolveRoomName,
     receiverName: input.resolveReceiverName,
     replied: input.resolveReplied,

src/events/decoders/messages.ts

@@ -30,7 +30,7 @@ export interface DecodeContext {
   selfName?: string
   lidMap?: Map<string, string>
   /** WhatsApp replays a reconnect's backlog as `append`; live traffic arrives as `notify`. */
-  isOffline?: boolean
+  isOld?: boolean
   logger?: DownloadLogger
   channelId?: string
   receiverId?: string
@@ -774,14 +774,14 @@ const buildContext = (
     isForwarded,
     isBroadcast,
     isNewsletter,
-    isOffline: ctx.isOffline === true,
+    isOld: ctx.isOld === true,
+    prefixes,
     forwardCount: numOr(contextInfo?.forwardingScore, 0),
     ephemeralDuration: ephemeralDurationOf(msg, contextInfo),
     addressingMode: key.addressingMode === 'lid' ? ('lid' as const) : ('pn' as const),
     mentionedGroups: groupMentionsOf(contextInfo),
     ...(ad !== undefined ? { ad } : {}),
     ...(business !== undefined ? { business } : {}),
-    prefixes,
     ...(ctx.lidMap != null ? { lidMap: ctx.lidMap } : {}),
     resolveRoomName,
     resolveReceiverName,
@@ -816,11 +816,11 @@ const buildMediaAttachment = (
     fileName: typeof node.fileName === 'string' ? node.fileName : null,
     fileSize: toNum(node.fileLength),
     ptt: node.ptt === true,
+    isAnimated: node.isAnimated === true || node.gifPlayback === true,
     duration: toNum(node.seconds),
     width: toNum(node.width),
     height: toNum(node.height),
     pages: toNum(node.pageCount),
-    isAnimated: node.isAnimated === true || node.gifPlayback === true,
     thumbnail: node.jpegThumbnail != null ? Buffer.from(node.jpegThumbnail) : null,
     buffer: async () => (await bufferFn()).buffer,
     stream: streamFn,

src/events/pipeline.ts

@@ -226,7 +226,7 @@ export function attachInboundPipeline(
 
   subscribe('messages.upsert', (raw) => {
     const upsert = dropSpoofedSelfOnly(raw as UpsertPayload)
-    const baseCtx = upsert.type === 'append' ? { ...decodeCtx, isOffline: true } : decodeCtx
+    const baseCtx = upsert.type === 'append' ? { ...decodeCtx, isOld: true } : decodeCtx
     for (const msg of upsert.messages) {
       if (ctx.ignoreMe === true && msg.key?.fromMe === true) continue
       const lids = ctx.resolveLidToPn != null ? lidTargetsOf(msg) : []

tests/command/dispatcher.test.ts

@@ -19,7 +19,7 @@ const msg = (text: string): MessageContext => ({
   senderLid: null,
   senderName: null,
   senderUsername: null,
-  isOffline: false,
+  isOld: false,
   forwardCount: 0,
   ephemeralDuration: null,
   addressingMode: 'pn',

tests/events/payload-additions.test.ts

@@ -38,13 +38,13 @@ const emit = (messages: Record<string, unknown>[], type = 'notify'): MessageCont
   return seen.mock.calls[0]?.[0] as MessageContext
 }
 
-describe('isOffline', () => {
+describe('isOld', () => {
   it('is false for live traffic', () => {
-    expect(emit([msg()]).isOffline).toBe(false)
+    expect(emit([msg()]).isOld).toBe(false)
   })
 
   it('is true for the backlog WhatsApp replays after a reconnect', () => {
-    expect(emit([msg()], 'append').isOffline).toBe(true)
+    expect(emit([msg()], 'append').isOld).toBe(true)
   })
 })