agent-messenger 2.27.1 → 2.28.0

package/src/platforms/instagram/hybrid-listener.ts

@@ -0,0 +1,196 @@
+import { EventEmitter } from 'node:events'
+
+import type { InstagramClient } from './client'
+import { InstagramListener } from './listener'
+import { InstagramRealtimeListener } from './realtime-listener'
+import type { InstagramMessageSummary } from './types'
+
+export interface InstagramHybridListenerEventMap {
+  message: [InstagramMessageSummary]
+  error: [Error]
+  connected: [{ userId: string; transport: 'realtime' | 'polling' }]
+  disconnected: []
+}
+
+type EventKey = keyof InstagramHybridListenerEventMap
+
+const DEFAULT_REALTIME_RETRY_BASE_MS = 30_000
+const DEFAULT_REALTIME_RETRY_MAX_MS = 5 * 60_000
+
+export interface InstagramHybridListenerOptions {
+  pollInterval?: number
+  realtimeRetryBaseMs?: number
+  realtimeRetryMaxMs?: number
+  disableRealtime?: boolean
+  connackTimeoutMs?: number
+}
+
+export class InstagramHybridListener {
+  private client: InstagramClient
+  private emitter = new EventEmitter()
+  private realtime: InstagramRealtimeListener | null = null
+  private poller: InstagramListener | null = null
+  private options: Required<
+    Pick<InstagramHybridListenerOptions, 'realtimeRetryBaseMs' | 'realtimeRetryMaxMs' | 'disableRealtime'>
+  > &
+    Pick<InstagramHybridListenerOptions, 'pollInterval' | 'connackTimeoutMs'>
+  private running = false
+  private realtimeRetryTimer: ReturnType<typeof setTimeout> | null = null
+  private realtimeFailures = 0
+  private activeTransport: 'realtime' | 'polling' | null = null
+  private tearingDownRealtime = false
+
+  constructor(client: InstagramClient, options: InstagramHybridListenerOptions = {}) {
+    this.client = client
+    this.options = {
+      pollInterval: options.pollInterval,
+      realtimeRetryBaseMs: options.realtimeRetryBaseMs ?? DEFAULT_REALTIME_RETRY_BASE_MS,
+      realtimeRetryMaxMs: options.realtimeRetryMaxMs ?? DEFAULT_REALTIME_RETRY_MAX_MS,
+      disableRealtime: options.disableRealtime ?? false,
+      connackTimeoutMs: options.connackTimeoutMs,
+    }
+  }
+
+  async start(): Promise<void> {
+    if (this.running) return
+    this.running = true
+
+    if (this.options.disableRealtime) {
+      this.startPolling()
+      return
+    }
+
+    await this.tryRealtime()
+  }
+
+  stop(): void {
+    this.running = false
+    this.activeTransport = null
+    this.clearRealtimeRetry()
+    this.teardownRealtime()
+    this.teardownPolling()
+    this.emitter.emit('disconnected')
+  }
+
+  on<K extends EventKey>(event: K, listener: (...args: InstagramHybridListenerEventMap[K]) => void): this {
+    this.emitter.on(event, listener as (...args: unknown[]) => void)
+    return this
+  }
+
+  off<K extends EventKey>(event: K, listener: (...args: InstagramHybridListenerEventMap[K]) => void): this {
+    this.emitter.off(event, listener as (...args: unknown[]) => void)
+    return this
+  }
+
+  once<K extends EventKey>(event: K, listener: (...args: InstagramHybridListenerEventMap[K]) => void): this {
+    this.emitter.once(event, listener as (...args: unknown[]) => void)
+    return this
+  }
+
+  protected createRealtimeListener(): InstagramRealtimeListener {
+    return new InstagramRealtimeListener(this.client, { connackTimeoutMs: this.options.connackTimeoutMs })
+  }
+
+  private async tryRealtime(): Promise<void> {
+    const realtime = this.createRealtimeListener()
+    this.realtime = realtime
+
+    realtime.on('message', (message) => this.emitter.emit('message', message))
+    realtime.on('connected', ({ userId }) => {
+      this.realtimeFailures = 0
+      this.activeTransport = 'realtime'
+      this.teardownPolling()
+      this.emitter.emit('connected', { userId, transport: 'realtime' })
+    })
+    realtime.on('error', (error) => this.onRealtimeFailure(error))
+    realtime.on('disconnected', () => {
+      // Ignore the 'disconnected' that our own teardown triggers; only an
+      // unexpected close (still marked realtime-active) is a real failure.
+      if (this.tearingDownRealtime) return
+      if (this.running && this.activeTransport === 'realtime') {
+        this.onRealtimeFailure(new Error('Realtime connection closed'))
+      }
+    })
+
+    try {
+      await realtime.start()
+      // stop() may have run during the bootstrap await; if so, don't leave an MQTT
+      // connection alive after the hybrid listener was already torn down.
+      if (!this.running) {
+        realtime.stop()
+        if (this.realtime === realtime) this.realtime = null
+      }
+    } catch (error) {
+      this.onRealtimeFailure(error instanceof Error ? error : new Error(String(error)))
+    }
+  }
+
+  private onRealtimeFailure(error: Error): void {
+    if (!this.running) return
+
+    this.activeTransport = null
+    this.emitter.emit('error', error)
+    this.realtimeFailures++
+    // teardownRealtime() suppresses the 'disconnected' it triggers, so this path
+    // does not re-enter via the realtime disconnected handler.
+    this.teardownRealtime()
+    this.startPolling()
+    this.scheduleRealtimeRetry()
+  }
+
+  private scheduleRealtimeRetry(): void {
+    if (!this.running || this.realtimeRetryTimer) return
+
+    const delay = Math.min(
+      this.options.realtimeRetryBaseMs * 2 ** (this.realtimeFailures - 1),
+      this.options.realtimeRetryMaxMs,
+    )
+
+    this.realtimeRetryTimer = setTimeout(() => {
+      this.realtimeRetryTimer = null
+      if (this.running) void this.tryRealtime()
+    }, delay)
+  }
+
+  private startPolling(): void {
+    if (this.poller) return
+
+    const poller = new InstagramListener(this.client, { pollInterval: this.options.pollInterval })
+    this.poller = poller
+
+    poller.on('message', (message) => this.emitter.emit('message', message))
+    poller.on('error', (error) => this.emitter.emit('error', error))
+    poller.on('connected', ({ userId }) => {
+      this.activeTransport = 'polling'
+      this.emitter.emit('connected', { userId, transport: 'polling' })
+    })
+
+    void poller.start()
+  }
+
+  private teardownRealtime(): void {
+    if (this.realtime) {
+      this.tearingDownRealtime = true
+      try {
+        this.realtime.stop()
+      } finally {
+        this.tearingDownRealtime = false
+      }
+      this.realtime = null
+    }
+  }
+
+  private teardownPolling(): void {
+    if (this.poller) {
+      this.poller.stop()
+      this.poller = null
+    }
+  }
+
+  private clearRealtimeRetry(): void {
+    if (this.realtimeRetryTimer) {
+      clearTimeout(this.realtimeRetryTimer)
+      this.realtimeRetryTimer = null
+    }
+  }
+}

package/src/platforms/instagram/index.ts

@@ -1,6 +1,16 @@
 export { InstagramClient } from './client'
 export { InstagramCredentialManager } from './credential-manager'
+export {
+  InstagramHybridListener,
+  type InstagramHybridListenerEventMap,
+  type InstagramHybridListenerOptions,
+} from './hybrid-listener'
 export { InstagramListener, type InstagramListenerEventMap } from './listener'
+export {
+  InstagramRealtimeListener,
+  type InstagramRealtimeListenerEventMap,
+  type InstagramRealtimeListenerOptions,
+} from './realtime-listener'
 export { InstagramTokenExtractor, type ExtractedInstagramCookies } from './token-extractor'
 export {
   createAccountId,

package/src/platforms/instagram/mqtt/connection.ts

@@ -0,0 +1,72 @@
+import { deflateSync } from 'node:zlib'
+
+import type { InstagramSessionState } from '../types'
+import { ThriftCompactWriter } from './thrift'
+
+const IG_APP_ID = 567067343352427n
+const IG_VERSION = '312.1.0.34.111'
+const CLIENT_CAPABILITIES = 183n
+const PUBLISH_FORMAT = 1
+const NETWORK_TYPE_WIFI = 1
+const CLIENT_STACK = 3
+const CLIENT_IDENTIFIER_MAX_LENGTH = 20
+const SESSION_ID_MASK = 0xffffffffn
+
+const CONNECT_SUBSCRIBE_TOPIC_IDS = [88, 135, 149, 150, 133, 146]
+
+export function extractSessionId(session: InstagramSessionState): string {
+  const authorization = session.authorization ?? ''
+  const igTokenMatch = authorization.match(/^Bearer IGT:2:(.+)$/)
+  if (igTokenMatch) {
+    try {
+      const decoded = JSON.parse(Buffer.from(igTokenMatch[1]!, 'base64').toString('utf8')) as { sessionid?: string }
+      if (decoded.sessionid) return decoded.sessionid
+    } catch {
+      // Malformed/stale token: fall through to the cookie-based sessionid below.
+    }
+  }
+
+  const cookieMatch = session.cookies.match(/sessionid=([^;]+)/)
+  if (cookieMatch) return cookieMatch[1]!
+
+  throw new Error('No sessionid found in Instagram session (checked authorization token and cookies)')
+}
+
+export function buildConnectPayload(session: InstagramSessionState): Buffer {
+  const sessionId = extractSessionId(session)
+  const userId = BigInt(session.user_id ?? '0')
+  const deviceId = session.device.phone_id
+  const userAgent = `Instagram ${IG_VERSION} Android (${session.device.device_string})`
+
+  const thrift = new ThriftCompactWriter()
+    .binary(1, deviceId.substring(0, CLIENT_IDENTIFIER_MAX_LENGTH))
+    .structStart(4)
+    .i64(1, userId)
+    .binary(2, userAgent)
+    .i64(3, CLIENT_CAPABILITIES)
+    .i64(4, 0)
+    .i32(5, PUBLISH_FORMAT)
+    .bool(6, false)
+    .bool(7, true)
+    .binary(8, deviceId)
+    .bool(9, true)
+    .i32(10, NETWORK_TYPE_WIFI)
+    .i32(11, 0)
+    .i64(12, BigInt(Date.now()) & SESSION_ID_MASK)
+    .listOfI32(14, CONNECT_SUBSCRIBE_TOPIC_IDS)
+    .binary(15, 'cookie_auth')
+    .i64(16, IG_APP_ID)
+    .binary(20, '')
+    .byte(21, CLIENT_STACK)
+    .structEnd()
+    .binary(5, `sessionid=${sessionId}`)
+    .mapBinaryBinary(10, {
+      platform: 'android',
+      ig_mqtt_route: 'django',
+      pubsub_msg_type_blacklist: 'direct, typing_type',
+      auth_cache_enabled: '0',
+    })
+    .finish()
+
+  return deflateSync(thrift, { level: 9 })
+}

package/src/platforms/instagram/mqtt/thrift.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'bun:test'
+
+import { ThriftCompactWriter } from '@/platforms/instagram/mqtt/thrift'
+
+describe('ThriftCompactWriter', () => {
+  it('encodes a true bool as a packed field header with a trailing stop byte', () => {
+    // field id 1 (delta 1) << 4 | TYPE_TRUE(0x01) = 0x11, then struct stop 0x00
+    const out = new ThriftCompactWriter().bool(1, true).finish()
+    expect([...out]).toEqual([0x11, 0x00])
+  })
+
+  it('encodes a false bool with the false type code', () => {
+    // field id 1 (delta 1) << 4 | TYPE_FALSE(0x02) = 0x12
+    const out = new ThriftCompactWriter().bool(1, false).finish()
+    expect([...out]).toEqual([0x12, 0x00])
+  })
+
+  it('encodes i32 using zigzag varint', () => {
+    // field 1 i32(0x05) = 0x15, zigzag(1) = 2
+    const out = new ThriftCompactWriter().i32(1, 1).finish()
+    expect([...out]).toEqual([0x15, 0x02, 0x00])
+  })
+
+  it('encodes negative i32 via zigzag', () => {
+    // zigzag(-1) = 1
+    const out = new ThriftCompactWriter().i32(1, -1).finish()
+    expect([...out]).toEqual([0x15, 0x01, 0x00])
+  })
+
+  it('encodes a large positive i32 as an unsigned <=5-byte varint', () => {
+    // 0x40000000: zigzag(1073741824) = 2147483648 = 0x80000000 -> varint 80 80 80 80 08
+    const out = new ThriftCompactWriter().i32(1, 0x40000000).finish()
+    expect([...out]).toEqual([0x15, 0x80, 0x80, 0x80, 0x80, 0x08, 0x00])
+  })
+
+  it('encodes INT32_MIN without overflowing into a 64-bit varint', () => {
+    // zigzag(-2147483648) = 4294967295 = 0xFFFFFFFF -> varint ff ff ff ff 0f (5 bytes, not 9)
+    const out = new ThriftCompactWriter().i32(1, -2147483648).finish()
+    expect([...out]).toEqual([0x15, 0xff, 0xff, 0xff, 0xff, 0x0f, 0x00])
+  })
+
+  it('encodes binary as length-prefixed utf8', () => {
+    // field 1 binary(0x08) = 0x18, length 2, "hi"
+    const out = new ThriftCompactWriter().binary(1, 'hi').finish()
+    expect([...out]).toEqual([0x18, 0x02, 0x68, 0x69, 0x00])
+  })
+
+  it('packs small field-id deltas across multiple fields', () => {
+    // field 1 binary = 0x18, then field 3 binary uses delta 2 = 0x28
+    const out = new ThriftCompactWriter().binary(1, 'a').binary(3, 'b').finish()
+    expect([...out]).toEqual([0x18, 0x01, 0x61, 0x28, 0x01, 0x62, 0x00])
+  })
+
+  it('falls back to explicit zigzag id when delta exceeds 15', () => {
+    // field 20 binary: delta 20 > 15, so type byte 0x08 then zigzag(20)=40=0x28
+    const out = new ThriftCompactWriter().binary(20, 'x').finish()
+    expect([...out]).toEqual([0x08, 0x28, 0x01, 0x78, 0x00])
+  })
+
+  it('encodes a short i32 list with size packed into the header nibble', () => {
+    // field 1 list = 0x19, list header size 2 << 4 | i32(0x05) = 0x25, zigzag(88)=176=0xb0 0x01, zigzag(146)=292=0xa4 0x02
+    const out = new ThriftCompactWriter().listOfI32(1, [88, 146]).finish()
+    expect([...out]).toEqual([0x19, 0x25, 0xb0, 0x01, 0xa4, 0x02, 0x00])
+  })
+
+  it('encodes an empty map as a single zero byte', () => {
+    // field 1 map = 0x1b, empty map size 0x00
+    const out = new ThriftCompactWriter().mapBinaryBinary(1, {}).finish()
+    expect([...out]).toEqual([0x1b, 0x00, 0x00])
+  })
+
+  it('encodes a binary->binary map with the key/value type byte', () => {
+    // field 1 map = 0x1b, size 1, types (binary<<4|binary)=0x88, key "k", value "v"
+    const out = new ThriftCompactWriter().mapBinaryBinary(1, { k: 'v' }).finish()
+    expect([...out]).toEqual([0x1b, 0x01, 0x88, 0x01, 0x6b, 0x01, 0x76, 0x00])
+  })
+
+  it('resets field-id delta tracking inside nested structs', () => {
+    // field 4 struct = 0x4c, inner field 1 binary = 0x18 "a", inner stop 0x00, outer stop 0x00
+    const out = new ThriftCompactWriter().structStart(4).binary(1, 'a').structEnd().finish()
+    expect([...out]).toEqual([0x4c, 0x18, 0x01, 0x61, 0x00, 0x00])
+  })
+
+  it('encodes i64 values larger than 32 bits', () => {
+    // field 16 i64: delta 16 > 15 -> type 0x06, zigzag id(16)=32=0x20, then zigzag64(567067343352427)
+    const out = new ThriftCompactWriter().i64(16, 567067343352427n).finish()
+    expect(out[0]).toBe(0x06)
+    expect(out[1]).toBe(0x20)
+    expect(out[out.length - 1]).toBe(0x00)
+  })
+})

package/src/platforms/instagram/mqtt/thrift.ts

@@ -0,0 +1,159 @@
+const TYPE_TRUE = 0x01
+const TYPE_FALSE = 0x02
+const TYPE_BYTE = 0x03
+const TYPE_I16 = 0x04
+const TYPE_I32 = 0x05
+const TYPE_I64 = 0x06
+const TYPE_BINARY = 0x08
+const TYPE_LIST = 0x09
+const TYPE_MAP = 0x0b
+const TYPE_STRUCT = 0x0c
+
+const VARINT_CONTINUE = 0x80
+const VARINT_MASK = 0x7f
+const U64_MASK = 0xffffffffffffffffn
+
+export class ThriftCompactWriter {
+  private bytes: number[] = []
+  private parentFieldStack: number[] = []
+  private lastFieldId = 0
+
+  bool(id: number, value: boolean): this {
+    this.writeFieldHeader(value ? TYPE_TRUE : TYPE_FALSE, id)
+    return this
+  }
+
+  byte(id: number, value: number): this {
+    this.writeFieldHeader(TYPE_BYTE, id)
+    this.bytes.push(value & 0xff)
+    return this
+  }
+
+  i16(id: number, value: number): this {
+    this.writeFieldHeader(TYPE_I16, id)
+    this.writeVarint(zigzag32(value))
+    return this
+  }
+
+  i32(id: number, value: number): this {
+    this.writeFieldHeader(TYPE_I32, id)
+    this.writeVarint(zigzag32(value))
+    return this
+  }
+
+  i64(id: number, value: number | bigint): this {
+    this.writeFieldHeader(TYPE_I64, id)
+    this.writeVarint(zigzag64(BigInt(value)))
+    return this
+  }
+
+  binary(id: number, value: string | Buffer): this {
+    this.writeFieldHeader(TYPE_BINARY, id)
+    this.writeBinaryValue(value)
+    return this
+  }
+
+  listOfI32(id: number, values: number[]): this {
+    this.writeFieldHeader(TYPE_LIST, id)
+    this.writeListHeader(TYPE_I32, values.length)
+    for (const value of values) this.writeVarint(zigzag32(value))
+    return this
+  }
+
+  listOfBinary(id: number, values: string[]): this {
+    this.writeFieldHeader(TYPE_LIST, id)
+    this.writeListHeader(TYPE_BINARY, values.length)
+    for (const value of values) this.writeBinaryValue(value)
+    return this
+  }
+
+  mapBinaryBinary(id: number, entries: Record<string, string>): this {
+    this.writeFieldHeader(TYPE_MAP, id)
+    const keys = Object.keys(entries)
+
+    // Compact protocol encodes an empty map as a single zero byte (size only).
+    if (keys.length === 0) {
+      this.bytes.push(0)
+      return this
+    }
+
+    this.writeVarint(keys.length)
+    this.bytes.push((TYPE_BINARY << 4) | TYPE_BINARY)
+    for (const key of keys) {
+      this.writeBinaryValue(key)
+      this.writeBinaryValue(entries[key]!)
+    }
+    return this
+  }
+
+  structStart(id: number): this {
+    this.writeFieldHeader(TYPE_STRUCT, id)
+    this.parentFieldStack.push(this.lastFieldId)
+    this.lastFieldId = 0
+    return this
+  }
+
+  structEnd(): this {
+    this.bytes.push(0)
+    this.lastFieldId = this.parentFieldStack.pop() ?? 0
+    return this
+  }
+
+  finish(): Buffer {
+    this.bytes.push(0)
+    return Buffer.from(this.bytes)
+  }
+
+  // Compact protocol packs a small field-id delta and the type into one byte
+  // (delta << 4 | type); deltas outside 1..15 fall back to a zigzag varint id.
+  private writeFieldHeader(type: number, id: number): void {
+    const delta = id - this.lastFieldId
+    if (delta > 0 && delta <= 15) {
+      this.bytes.push((delta << 4) | type)
+    } else {
+      this.bytes.push(type)
+      this.writeVarint(zigzag32(id))
+    }
+    this.lastFieldId = id
+  }
+
+  // Lists with fewer than 15 elements pack size into the header nibble;
+  // larger lists set the nibble to 0xf and append the size as a varint.
+  private writeListHeader(elementType: number, size: number): void {
+    if (size < 15) {
+      this.bytes.push((size << 4) | elementType)
+    } else {
+      this.bytes.push(0xf0 | elementType)
+      this.writeVarint(size)
+    }
+  }
+
+  private writeBinaryValue(value: string | Buffer): void {
+    const buf = Buffer.isBuffer(value) ? value : Buffer.from(value, 'utf8')
+    this.writeVarint(buf.length)
+    for (const b of buf) this.bytes.push(b)
+  }
+
+  private writeVarint(value: number | bigint): void {
+    let remaining = BigInt(value) & U64_MASK
+    while (true) {
+      const chunk = Number(remaining & BigInt(VARINT_MASK))
+      remaining >>= 7n
+      if (remaining === 0n) {
+        this.bytes.push(chunk)
+        return
+      }
+      this.bytes.push(chunk | VARINT_CONTINUE)
+    }
+  }
+}
+
+function zigzag32(value: number): number {
+  // `>>> 0` coerces the signed int32 bitwise result to an unsigned 32-bit value,
+  // so large positives and INT32_MIN encode as a <=5-byte varint, not a 64-bit one.
+  return ((value << 1) ^ (value >> 31)) >>> 0
+}
+
+function zigzag64(value: bigint): bigint {
+  return BigInt.asUintN(64, value << 1n) ^ (value >> 63n)
+}