agent-messenger 2.15.1 → 2.16.0

package/src/platforms/kakaotalk/image-meta.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'bun:test'
+
+import { detectImageDimensions } from './image-meta'
+
+function buildPng(width: number, height: number, opts?: { skipTrailingMagic?: boolean }): Uint8Array {
+  const buf = new Uint8Array(24)
+  const sig = opts?.skipTrailingMagic
+    ? [0x89, 0x50, 0x4e, 0x47, 0x00, 0x00, 0x00, 0x00]
+    : [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+  buf.set(sig, 0)
+  const view = new DataView(buf.buffer)
+  view.setUint32(16, width, false)
+  view.setUint32(20, height, false)
+  return buf
+}
+
+function buildGif(version: '87a' | '89a' | 'XXa', width: number, height: number): Uint8Array {
+  const buf = new Uint8Array(10)
+  buf.set([0x47, 0x49, 0x46], 0)
+  if (version === '87a') buf.set([0x38, 0x37, 0x61], 3)
+  else if (version === '89a') buf.set([0x38, 0x39, 0x61], 3)
+  else buf.set([0x00, 0x00, 0x00], 3)
+  const view = new DataView(buf.buffer)
+  view.setUint16(6, width, true)
+  view.setUint16(8, height, true)
+  return buf
+}
+
+function buildJpeg(opts: {
+  width: number
+  height: number
+  prefixFillBytes?: number
+  includeStandaloneMarkers?: boolean
+}): Uint8Array {
+  const parts: number[] = [0xff, 0xd8]
+  if (opts.includeStandaloneMarkers) {
+    parts.push(0xff, 0xd0, 0xff, 0xd9)
+  }
+  for (let i = 0; i < (opts.prefixFillBytes ?? 0); i++) parts.push(0xff)
+  parts.push(0xff, 0xc0)
+  parts.push(0x00, 0x11)
+  parts.push(0x08)
+  parts.push((opts.height >> 8) & 0xff, opts.height & 0xff)
+  parts.push((opts.width >> 8) & 0xff, opts.width & 0xff)
+  for (let i = 0; i < 10; i++) parts.push(0x00)
+  return new Uint8Array(parts)
+}
+
+describe('detectImageDimensions', () => {
+  it('reads PNG dimensions when the full 8-byte signature is present', () => {
+    const dim = detectImageDimensions(buildPng(320, 240))
+    expect(dim).toEqual({ width: 320, height: 240, mimeType: 'image/png' })
+  })
+
+  it('rejects PNG-look-alikes that share only the first 4 bytes', () => {
+    expect(() => detectImageDimensions(buildPng(1, 1, { skipTrailingMagic: true }))).toThrow(/Unsupported/)
+  })
+
+  it('reads GIF87a and GIF89a dimensions', () => {
+    expect(detectImageDimensions(buildGif('87a', 100, 200))).toEqual({
+      width: 100,
+      height: 200,
+      mimeType: 'image/gif',
+    })
+    expect(detectImageDimensions(buildGif('89a', 64, 32))).toEqual({
+      width: 64,
+      height: 32,
+      mimeType: 'image/gif',
+    })
+  })
+
+  it('rejects GIF-look-alikes with the wrong version bytes', () => {
+    expect(() => detectImageDimensions(buildGif('XXa', 100, 200))).toThrow(/Unsupported/)
+  })
+
+  it('reads JPEG dimensions from a plain SOF0 marker', () => {
+    const dim = detectImageDimensions(buildJpeg({ width: 800, height: 600 }))
+    expect(dim).toEqual({ width: 800, height: 600, mimeType: 'image/jpeg' })
+  })
+
+  it('reads JPEG dimensions when 0xFF fill bytes precede the SOF marker', () => {
+    const dim = detectImageDimensions(buildJpeg({ width: 1280, height: 720, prefixFillBytes: 5 }))
+    expect(dim).toEqual({ width: 1280, height: 720, mimeType: 'image/jpeg' })
+  })
+
+  it('reads JPEG dimensions past standalone markers (RST/SOI/EOI) without desyncing', () => {
+    const dim = detectImageDimensions(buildJpeg({ width: 42, height: 99, includeStandaloneMarkers: true }))
+    expect(dim).toEqual({ width: 42, height: 99, mimeType: 'image/jpeg' })
+  })
+})

package/src/platforms/kakaotalk/image-meta.ts

@@ -0,0 +1,176 @@
+export interface ImageDimensions {
+  width: number
+  height: number
+  mimeType: string
+}
+
+// Extracts width/height/mime by reading the file's magic bytes and headers
+// directly. Avoids pulling in `image-size` or `sharp` so the SDK stays
+// dependency-light. Supports JPEG, PNG, GIF, WebP — the formats KakaoTalk
+// actually renders inline. Throws for anything else (including truncated
+// headers whose magic matches but whose length is short of the dimension
+// fields, to avoid an unhandled DataView RangeError); the caller should fall
+// back to `sendFile` (type=18) for unknown types.
+export function detectImageDimensions(buffer: Uint8Array): ImageDimensions {
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+
+  if (isPng(buffer)) {
+    if (buffer.length < 24) {
+      throw new Error('Truncated PNG: header is shorter than 24 bytes')
+    }
+    return {
+      width: view.getUint32(16, false),
+      height: view.getUint32(20, false),
+      mimeType: 'image/png',
+    }
+  }
+
+  if (isJpeg(buffer)) {
+    const dim = readJpegDimensions(buffer)
+    return { ...dim, mimeType: 'image/jpeg' }
+  }
+
+  if (isGif(buffer)) {
+    if (buffer.length < 10) {
+      throw new Error('Truncated GIF: header is shorter than 10 bytes')
+    }
+    return {
+      width: view.getUint16(6, true),
+      height: view.getUint16(8, true),
+      mimeType: 'image/gif',
+    }
+  }
+
+  if (isWebp(buffer)) {
+    if (buffer.length < 16) {
+      throw new Error('Truncated WebP: header is shorter than 16 bytes')
+    }
+    return { ...readWebpDimensions(buffer), mimeType: 'image/webp' }
+  }
+
+  throw new Error('Unsupported image format (expected JPEG, PNG, GIF, or WebP)')
+}
+
+// Full PNG signature: 89 50 4E 47 0D 0A 1A 0A — checking only the first 4 bytes
+// would let a file that happens to start with "\x89PNG" but isn't really a PNG
+// reach the dimension reader and either crash or return garbage. The trailing
+// CRLF/EOF/LF bytes pin it to a real PNG header.
+function isPng(b: Uint8Array): boolean {
+  return (
+    b[0] === 0x89 &&
+    b[1] === 0x50 &&
+    b[2] === 0x4e &&
+    b[3] === 0x47 &&
+    b[4] === 0x0d &&
+    b[5] === 0x0a &&
+    b[6] === 0x1a &&
+    b[7] === 0x0a
+  )
+}
+
+function isJpeg(b: Uint8Array): boolean {
+  return b[0] === 0xff && b[1] === 0xd8
+}
+
+// GIF signature is "GIF87a" or "GIF89a". Checking only "GIF" would match any
+// payload that starts with those three bytes (other Compuserve formats, etc.).
+function isGif(b: Uint8Array): boolean {
+  return (
+    b[0] === 0x47 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x38 &&
+    (b[4] === 0x37 || b[4] === 0x39) &&
+    b[5] === 0x61
+  )
+}
+
+function isWebp(b: Uint8Array): boolean {
+  return (
+    b[0] === 0x52 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x46 &&
+    b[8] === 0x57 &&
+    b[9] === 0x45 &&
+    b[10] === 0x42 &&
+    b[11] === 0x50
+  )
+}
+
+// JPEG dimensions live in an SOF (Start Of Frame) marker (0xFFC0..0xFFCF except
+// 0xFFC4, 0xFFC8, 0xFFCC which are not SOF). We scan markers until we hit one.
+//
+// The scan has to handle two JPEG quirks (ITU-T T.81 §B.1):
+//   1. Fill bytes — any number of 0xFF bytes may precede a marker, so on a
+//      0xFF byte we look at the next byte for the actual marker code and skip
+//      forward by 1 if it's another 0xFF (without trying to read a length).
+//   2. Standalone markers — SOI/EOI/RST0-7/TEM (0xFFD0..0xFFD9, 0xFF01) have
+//      no length field, so we step past them with a fixed +2 instead of
+//      reading garbage as a segment length.
+// Treating either case as a length-prefixed segment desynchronizes the scan
+// and either skips past the SOF or runs off the end of the buffer.
+function readJpegDimensions(buffer: Uint8Array): { width: number; height: number } {
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+  let i = 2
+  while (i < buffer.length - 9) {
+    if (buffer[i] !== 0xff) {
+      i++
+      continue
+    }
+    const marker = buffer[i + 1] ?? 0
+    if (marker === 0xff) {
+      i++
+      continue
+    }
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      const height = view.getUint16(i + 5, false)
+      const width = view.getUint16(i + 7, false)
+      return { width, height }
+    }
+    if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+      i += 2
+      continue
+    }
+    const segmentLength = view.getUint16(i + 2, false)
+    i += 2 + segmentLength
+  }
+  throw new Error('JPEG SOF marker not found')
+}
+
+// WebP supports several variants: VP8 (lossy), VP8L (lossless), VP8X (extended).
+// Dimensions live at different offsets per variant; we cover all three.
+function readWebpDimensions(buffer: Uint8Array): { width: number; height: number } {
+  const view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength)
+  const fourCC = String.fromCharCode(buffer[12]!, buffer[13]!, buffer[14]!, buffer[15]!)
+
+  if (fourCC === 'VP8 ') {
+    if (buffer.length < 30) {
+      throw new Error('Truncated WebP VP8: header is shorter than 30 bytes')
+    }
+    const width = view.getUint16(26, true) & 0x3fff
+    const height = view.getUint16(28, true) & 0x3fff
+    return { width, height }
+  }
+  if (fourCC === 'VP8L') {
+    if (buffer.length < 25) {
+      throw new Error('Truncated WebP VP8L: header is shorter than 25 bytes')
+    }
+    const b0 = buffer[21]!
+    const b1 = buffer[22]!
+    const b2 = buffer[23]!
+    const b3 = buffer[24]!
+    const width = 1 + (((b1 & 0x3f) << 8) | b0)
+    const height = 1 + (((b3 & 0x0f) << 10) | (b2 << 2) | ((b1 & 0xc0) >> 6))
+    return { width, height }
+  }
+  if (fourCC === 'VP8X') {
+    if (buffer.length < 31) {
+      throw new Error('Truncated WebP VP8X: header is shorter than 31 bytes')
+    }
+    const width = 1 + (view.getUint32(24, true) & 0xffffff)
+    const height = 1 + (view.getUint32(27, true) & 0xffffff)
+    return { width, height }
+  }
+  throw new Error(`Unsupported WebP variant: ${fourCC}`)
+}

package/src/platforms/kakaotalk/index.ts

@@ -12,8 +12,10 @@ export type {
   KakaoDeviceType,
   KakaoEmoticonKind,
   KakaoEmoticonMessageType,
+  KakaoFileExtra,
   KakaoMember,
   KakaoMessage,
+  KakaoPhotoExtra,
   KakaoProfile,
   KakaoSendResult,
   KakaoTalkListenerEventMap,
@@ -27,6 +29,7 @@ export type {
 export {
   KAKAO_EMOTICON_KIND_BY_TYPE,
   KAKAO_EMOTICON_MESSAGE_TYPES,
+  KAKAO_MESSAGE_TYPE,
   KakaoAccountCredentialsSchema,
   KakaoChatSchema,
   KakaoConfigSchema,
@@ -39,3 +42,7 @@ export {
   KakaoTalkPushMessageEventSchema,
   KakaoTalkPushReadEventSchema,
 } from './types'
+export { sha1Hex } from './media-upload'
+export { detectImageDimensions } from './image-meta'
+export type { AttachmentInput, AttachmentPlan, ResolvedAttachment, SingleAttachmentKind } from './attachment-router'
+export { planAttachments, resolveAttachment } from './attachment-router'

package/src/platforms/kakaotalk/media-upload.ts

@@ -0,0 +1,44 @@
+// SHA-1 hex (uppercase, 40 chars) — required as the `cs` (checksum) field
+// on SHIP requests and on the inbound photo `extra` JSON. Verified by inbound
+// capture of a real KakaoTalk client photo (2026-05).
+export async function sha1Hex(data: Uint8Array): Promise<string> {
+  const hashBuf = await crypto.subtle.digest('SHA-1', data)
+  return Array.from(new Uint8Array(hashBuf))
+    .map((b) => b.toString(16).padStart(2, '0').toUpperCase())
+    .join('')
+}
+
+const MIME_BY_EXT: Record<string, string> = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  mp4: 'video/mp4',
+  mov: 'video/quicktime',
+  webm: 'video/webm',
+  mkv: 'video/x-matroska',
+  m4v: 'video/x-m4v',
+  m4a: 'audio/m4a',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  pdf: 'application/pdf',
+  csv: 'text/csv',
+  txt: 'text/plain',
+  json: 'application/json',
+  zip: 'application/zip',
+  doc: 'application/msword',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  xls: 'application/vnd.ms-excel',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  ppt: 'application/vnd.ms-powerpoint',
+  pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+}
+
+export function guessMimeFromFilename(filename: string): string {
+  const dot = filename.lastIndexOf('.')
+  if (dot < 0 || dot === filename.length - 1) return 'application/octet-stream'
+  const ext = filename.slice(dot + 1).toLowerCase()
+  return MIME_BY_EXT[ext] ?? 'application/octet-stream'
+}

package/src/platforms/kakaotalk/protocol/connection.ts

@@ -50,6 +50,17 @@ export class LocoConnection {
     await this.write(handshakePacket)
   }
 
+  // Writes raw bytes onto the LOCO stream after applying the same AES-128-GCM
+  // framing as encrypted packets — used by the media-upload POST step where
+  // the protocol expects the file payload to follow the POST request inside
+  // the same encrypted channel (chunked into N frames automatically by the
+  // crypto layer's 4-byte-size + nonce + ciphertext + tag wrapping).
+  async writeRaw(data: Buffer): Promise<void> {
+    if (!this.crypto) throw new Error('crypto not initialised')
+    const encrypted = this.crypto.encrypt(data)
+    await this.write(encrypted)
+  }
+
   async sendPacket(method: string, body: Record<string, unknown> = {}): Promise<LocoPacket> {
     const packetId = ++this.packetIdCounter
     const packet: LocoPacket = {

package/src/platforms/kakaotalk/protocol/media-uploader.ts

@@ -0,0 +1,129 @@
+import { Long } from 'bson'
+
+import type { KakaoDeviceType } from '../types'
+import { MCCMNC, getLocoDeviceConfig } from './config'
+import { LocoConnection } from './connection'
+import type { LocoPacket } from './types'
+
+export interface UploadToLocoOptions {
+  shipToken: string
+  shipHost: string
+  shipPort: number
+  chatId: Long
+  msgType: number
+  userId: string
+  filename: string
+  data: Uint8Array
+  width?: number
+  height?: number
+  deviceType: KakaoDeviceType
+  onProgress?: (sent: number, total: number) => void
+}
+
+export interface UploadToLocoResult {
+  completePacket: LocoPacket | null
+  postStatusCode: number
+  postOffset: number
+}
+
+const DEFAULT_NETWORK_TYPE = 0
+const DEFAULT_COMPLETE_TIMEOUT_MS = 60_000
+
+// Drives the SHIP → connect → POST → stream → COMPLETE pipeline that KakaoTalk
+// uses for chat-media uploads. The caller has already done SHIP on the main
+// session and received {k, vh, p}; this opens a dedicated TCP+LOCO connection
+// to (vh, p), sends POST with the ticket + chat metadata, streams the raw file
+// bytes, and waits for the server's COMPLETE push that triggers the actual
+// chat-message registration.
+//
+// Field names (u/k/t/s/c/mid/w/h/mm/nt/os/av/f/ns) match the APK's
+// `SR/g0.java` (PostJob) verbatim. The COMPLETE handshake is a server-pushed
+// packet whose body contains the resulting chatLog struct.
+export async function uploadMediaToLoco(opts: UploadToLocoOptions): Promise<UploadToLocoResult> {
+  return runPostStreamComplete(opts, 'POST')
+}
+
+// Single-entry MPOST upload — runs the same connect → POST → stream → COMPLETE
+// pipeline as uploadMediaToLoco but with MPOST as the opcode (used after MSHIP
+// for each entry in a multi-photo batch). Callers fan-out across all entries
+// in parallel and then issue one FORWARD to register the gallery message.
+export async function uploadMultiMediaEntry(opts: UploadToLocoOptions): Promise<UploadToLocoResult> {
+  return runPostStreamComplete(opts, 'MPOST')
+}
+
+async function runPostStreamComplete(opts: UploadToLocoOptions, opcode: 'POST' | 'MPOST'): Promise<UploadToLocoResult> {
+  const device = getLocoDeviceConfig(opts.deviceType)
+
+  const conn = new LocoConnection()
+  await conn.connectSecure(opts.shipHost, opts.shipPort)
+
+  const totalSize = opts.data.byteLength
+  let completeResolve: ((p: LocoPacket | null) => void) | null = null
+  let completeTimeout: ReturnType<typeof setTimeout> | null = null
+  const completePromise = new Promise<LocoPacket | null>((resolve) => {
+    completeResolve = resolve
+    completeTimeout = setTimeout(() => {
+      completeTimeout = null
+      resolve(null)
+    }, DEFAULT_COMPLETE_TIMEOUT_MS)
+  })
+  conn.onPush((push) => {
+    if (push.method === 'COMPLETE' && completeResolve) {
+      if (completeTimeout) {
+        clearTimeout(completeTimeout)
+        completeTimeout = null
+      }
+      completeResolve(push)
+      completeResolve = null
+    }
+  })
+
+  try {
+    const postBody: Record<string, unknown> = {
+      k: opts.shipToken,
+      s: totalSize,
+      t: opts.msgType,
+      u: Long.fromString(opts.userId),
+      os: device.os,
+      av: device.appVersion,
+      nt: DEFAULT_NETWORK_TYPE,
+      mm: MCCMNC,
+    }
+    if (opcode === 'POST') {
+      postBody.f = opts.filename
+      postBody.c = opts.chatId
+      postBody.mid = Long.ONE
+      postBody.ns = true
+      if (typeof opts.width === 'number') postBody.w = opts.width
+      if (typeof opts.height === 'number') postBody.h = opts.height
+    } else {
+      postBody.dt = 0
+      postBody.scp = 0
+    }
+
+    const postResp = await conn.sendPacket(opcode, postBody)
+    const postOffsetRaw = (postResp.body as Record<string, unknown>).o
+    const postOffset = typeof postOffsetRaw === 'number' ? postOffsetRaw : 0
+
+    const bytesToSend = opts.data.subarray(postOffset)
+    if (bytesToSend.length > 0) {
+      await conn.writeRaw(Buffer.from(bytesToSend))
+      opts.onProgress?.(totalSize, totalSize)
+    }
+
+    const completePacket = await completePromise
+    const postStatusCode = postResp.statusCode
+
+    return {
+      completePacket,
+      postStatusCode,
+      postOffset,
+    }
+  } finally {
+    if (completeTimeout) {
+      clearTimeout(completeTimeout)
+      completeTimeout = null
+    }
+    conn.close()
+  }
+}

package/src/platforms/kakaotalk/protocol/session.ts

@@ -126,6 +126,73 @@ export class LocoSession {
     })
   }
 
+  // Sends a WRITE with non-text message_type plus the JSON-stringified `extra`
+  // payload that KakaoTalk clients render as the attachment (photo, file, etc).
+  // See types.ts → KakaoPhotoExtra / KakaoFileExtra for the per-type shape.
+  async sendAttachment(chatId: Long, type: number, extra: Record<string, unknown>, caption = ''): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return this.connection.sendPacket('WRITE', {
+      chatId,
+      msg: caption,
+      type,
+      noSeen: false,
+      extra: JSON.stringify(extra),
+    })
+  }
+
+  // SHIP — request a media-upload ticket. Reserves a slot on a media LOCO
+  // server and returns the token (k), host (vh), and port (p) the client must
+  // connect to next. Sent on the main session.
+  async shipMedia(chatId: Long, type: number, size: number, checksum: string, extension: string): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    const body: Record<string, unknown> = {
+      c: chatId,
+      t: type,
+      s: Long.fromNumber(size),
+      cs: checksum,
+    }
+    if (extension.length > 0) body.e = extension
+    return this.connection.sendPacket('SHIP', body)
+  }
+
+  // MSHIP — multi-file equivalent of SHIP. Per-file fields become parallel
+  // arrays (sl/csl/el) and the response carries kl/vhl/pl arrays the caller
+  // must fan out across — one MPOST connection per entry.
+  async shipMultiMedia(
+    chatId: Long,
+    type: number,
+    sizes: number[],
+    checksums: string[],
+    extensions: string[],
+  ): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return this.connection.sendPacket('MSHIP', {
+      c: chatId,
+      t: type,
+      sl: sizes.map((s) => Long.fromNumber(s)),
+      csl: checksums,
+      el: extensions,
+    })
+  }
+
+  // FORWARD — used after MPOST: registers a multi-attachment chatlog as one
+  // message. Same shape as WRITE but the server routes the attachment to
+  // multi-media rendering (galleries, multi-photo posts).
+  async forwardChat(chatId: Long, type: number, extra: Record<string, unknown>, caption = ''): Promise<LocoPacket> {
+    if (!this.connection) throw new Error('Not connected')
+    return this.connection.sendPacket('FORWARD', {
+      chatId,
+      msg: caption,
+      type,
+      noSeen: false,
+      extra: JSON.stringify(extra),
+    })
+  }
+
+  getConnection(): LocoConnection | null {
+    return this.connection
+  }
+
   async syncMessages(chatId: Long, count = 20, cursor?: Long, maxLogId?: Long): Promise<LocoPacket> {
     if (!this.connection) throw new Error('Not connected')
     return this.connection.sendPacket('SYNCMSG', {

package/src/platforms/kakaotalk/types.ts

@@ -119,6 +119,63 @@ export interface KakaoSendResult {
   sent_at: number
 }
 
+// LOCO message_type values. Source: KakaoTalk APK 26.4.2 + typeclaw inbound parser.
+export const KAKAO_MESSAGE_TYPE = {
+  TEXT: 1,
+  PHOTO: 2,
+  VIDEO: 3,
+  AUDIO: 5,
+  FILE: 18,
+  MULTIPHOTO: 27,
+} as const
+
+// PHOTO `extra` keys verified by inbound capture of a real KakaoTalk client
+// photo message (2026-05). The bare minimum the receiver needs to render
+// the inline preview is k/s/w/h/mt/cs — url and thumbnailUrl are server-issued
+// pre-signed URLs that the recipient regenerates locally from k, so we don't
+// supply them on outbound.
+export interface KakaoPhotoExtra {
+  k: string
+  s: number
+  w: number
+  h: number
+  mt: string
+  cs: string
+  url?: string
+  thumbnailUrl?: string
+  thumbnailWidth?: number
+  thumbnailHeight?: number
+  expire?: number
+}
+
+export interface KakaoFileExtra {
+  k: string
+  s: number
+  name: string
+  mt: string
+  cs: string
+  expire?: number
+  url?: string
+}
+
+// MULTIPHOTO extra — each per-file field of KakaoPhotoExtra becomes a
+// parallel array. Verified by inbound capture of a real multi-photo message
+// (2026-05). csl uses lowercase hex (unlike PHOTO's cs which is uppercase).
+export interface KakaoMultiPhotoExtra {
+  kl: string[]
+  wl: number[]
+  hl: number[]
+  mtl: string[]
+  sl: number[]
+  csl: string[]
+  cmtl?: string[]
+  imageUrls?: string[]
+  thumbnailUrls?: string[]
+  thumbnailWidths?: number[]
+  thumbnailHeights?: number[]
+  expire?: number
+}
+
 export interface KakaoMarkReadResult {
   success: boolean
   status_code: number