agent-messenger 2.27.1 → 2.28.0

package/src/platforms/imessage/client.ts

@@ -0,0 +1,253 @@
+import { spawn } from 'node:child_process'
+
+import { classifyImsgFailure } from './errors'
+import { ImsgRpc } from './rpc'
+import { type IMessageChatSummary, type IMessageMessageSummary, type IMessageStatus, IMessageError } from './types'
+
+interface ImsgChat {
+  id: number
+  name?: string | null
+  identifier?: string | null
+  guid?: string | null
+  service?: string | null
+  is_group?: boolean
+  participants?: string[] | null
+  last_message?: ImsgMessage | null
+}
+
+interface ImsgMessage {
+  id: number
+  chat_id: number
+  guid: string
+  sender?: string | null
+  sender_name?: string | null
+  is_from_me?: boolean
+  text?: string | null
+  created_at?: string | null
+}
+
+const STANDARD_REACTIONS = new Set(['love', 'like', 'dislike', 'laugh', 'emphasis', 'question'])
+
+export interface SendTarget {
+  chatId?: number
+  chatGuid?: string
+  chatIdentifier?: string
+  to?: string
+}
+
+export type OneShotRunner = (
+  binaryPath: string,
+  args: string[],
+) => Promise<{ code: number; stdout: string; stderr: string }>
+
+const defaultRunner: OneShotRunner = (binaryPath, args) =>
+  new Promise((resolve, reject) => {
+    let proc: ReturnType<typeof spawn>
+    try {
+      proc = spawn(binaryPath, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    } catch {
+      reject(new IMessageError(`Could not run "${binaryPath}".`, 'imsg_not_found'))
+      return
+    }
+    let stdout = ''
+    let stderr = ''
+    proc.stdout?.on('data', (c: Buffer) => (stdout += c.toString()))
+    proc.stderr?.on('data', (c: Buffer) => (stderr += c.toString()))
+    proc.once('error', (err: NodeJS.ErrnoException) => {
+      reject(
+        err.code === 'ENOENT'
+          ? new IMessageError(`Could not run "${binaryPath}".`, 'imsg_not_found', {
+              suggestion: 'Install imsg: "brew install steipete/tap/imsg".',
+              doctorCommand: 'agent-imessage doctor',
+            })
+          : err,
+      )
+    })
+    proc.once('close', (code) => resolve({ code: code ?? 0, stdout, stderr }))
+  })
+
+function summarizeMessage(msg: ImsgMessage): IMessageMessageSummary {
+  return {
+    id: msg.id,
+    guid: msg.guid,
+    chat_id: msg.chat_id,
+    from: msg.is_from_me ? '' : (msg.sender ?? ''),
+    from_name: msg.sender_name ?? undefined,
+    is_outgoing: Boolean(msg.is_from_me),
+    timestamp: msg.created_at ?? new Date(0).toISOString(),
+    text: msg.text ?? undefined,
+  }
+}
+
+function summarizeChat(chat: ImsgChat): IMessageChatSummary {
+  return {
+    id: chat.id,
+    guid: chat.guid ?? null,
+    identifier: chat.identifier ?? null,
+    name: chat.name?.trim() || chat.identifier || chat.guid || String(chat.id),
+    service: chat.service ?? 'iMessage',
+    is_group: Boolean(chat.is_group),
+    participants: chat.participants ?? [],
+    last_message: chat.last_message ? summarizeMessage(chat.last_message) : undefined,
+  }
+}
+
+export class ImsgClient {
+  private binaryPath = 'imsg'
+  private region: string | undefined
+  private rpc: ImsgRpc
+  private runner: OneShotRunner
+
+  constructor(deps?: { rpc?: ImsgRpc; runner?: OneShotRunner }) {
+    this.rpc = deps?.rpc ?? new ImsgRpc()
+    this.runner = deps?.runner ?? defaultRunner
+  }
+
+  async login(credentials?: { binaryPath?: string; region?: string }): Promise<this> {
+    if (credentials) {
+      this.binaryPath = credentials.binaryPath ?? 'imsg'
+      this.region = credentials.region
+      return this
+    }
+    const { IMessageCredentialManager } = await import('./credential-manager')
+    const resolved = await new IMessageCredentialManager().resolveAccount()
+    this.binaryPath = resolved?.binary_path ?? 'imsg'
+    this.region = resolved?.region
+    return this
+  }
+
+  async connect(): Promise<void> {
+    await this.rpc.start(this.binaryPath)
+    await this.rpc.request('chats.list', { limit: 1 })
+  }
+
+  async getVersion(): Promise<string | null> {
+    const result = await this.runner(this.binaryPath, ['--version'])
+    if (result.code !== 0) return null
+    return result.stdout.trim() || null
+  }
+
+  async getStatus(): Promise<IMessageStatus> {
+    let version: string | null = null
+    let fullDiskAccess = false
+    try {
+      version = await this.getVersion()
+    } catch {
+      version = null
+    }
+    try {
+      await this.rpc.request('chats.list', { limit: 1 })
+      fullDiskAccess = true
+    } catch {
+      fullDiskAccess = false
+    }
+    return {
+      imsg_version: version,
+      binary_path: this.binaryPath,
+      full_disk_access: fullDiskAccess,
+      automation: 'unknown',
+      bridge_available: false,
+    }
+  }
+
+  async listChats(limit = 25): Promise<IMessageChatSummary[]> {
+    const result = await this.rpc.request<{ chats: ImsgChat[] }>('chats.list', { limit })
+    return result.chats.map(summarizeChat)
+  }
+
+  async searchChats(query: string, limit = 25): Promise<IMessageChatSummary[]> {
+    const all = await this.listChats(Math.max(limit, 100))
+    const lower = query.toLowerCase()
+    return all
+      .filter((c) => c.name.toLowerCase().includes(lower) || (c.identifier ?? '').toLowerCase().includes(lower))
+      .slice(0, limit)
+  }
+
+  async getMessages(chatId: number, limit = 25, start?: string): Promise<IMessageMessageSummary[]> {
+    const result = await this.rpc.request<{ messages: ImsgMessage[] }>('messages.history', {
+      chat_id: chatId,
+      limit,
+      ...(start ? { start } : {}),
+    })
+    return result.messages.map(summarizeMessage).sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+  }
+
+  async sendMessage(target: SendTarget, text: string): Promise<IMessageMessageSummary> {
+    const params: Record<string, unknown> = { text }
+    if (target.chatId !== undefined) params.chat_id = target.chatId
+    else if (target.chatGuid) params.chat_guid = target.chatGuid
+    else if (target.chatIdentifier) params.chat_identifier = target.chatIdentifier
+    else if (target.to) params.to = target.to
+    else throw new IMessageError('A chat id, guid, or recipient is required to send.', 'chat_not_found')
+    if (this.region) params.region = this.region
+
+    const result = await this.rpc.request<{ ok?: boolean; guid?: string; id?: number; service?: string }>(
+      'send',
+      params,
+    )
+    return {
+      id: result.id ?? 0,
+      guid: result.guid ?? '',
+      chat_id: target.chatId ?? 0,
+      from: '',
+      is_outgoing: true,
+      timestamp: new Date().toISOString(),
+      text,
+    }
+  }
+
+  async sendReaction(chatId: number, reaction: string, messageGuid?: string): Promise<void> {
+    if (messageGuid) {
+      throw new IMessageError(
+        'Reacting to a specific message requires the imsg Private API bridge.',
+        'private_api_required',
+        { suggestion: 'Enable the bridge with "imsg launch" (requires SIP disabled).' },
+      )
+    }
+    if (!STANDARD_REACTIONS.has(reaction)) {
+      throw new IMessageError(
+        `Custom reactions require the imsg Private API bridge. Standard tapbacks: ${[...STANDARD_REACTIONS].join(', ')}.`,
+        'private_api_required',
+        { suggestion: 'Enable the bridge with "imsg launch" (requires SIP disabled).' },
+      )
+    }
+    const result = await this.runner(this.binaryPath, [
+      'react',
+      '--chat-id',
+      String(chatId),
+      '--reaction',
+      reaction,
+      '--json',
+    ])
+    if (result.code !== 0) {
+      const detail = result.stderr.trim() || result.stdout.trim() || 'Reaction failed.'
+      throw classifyImsgFailure(detail, 'send_failed')
+    }
+  }
+
+  async watch(
+    onMessage: (msg: IMessageMessageSummary) => void,
+    options: { chatId?: number; sinceRowId?: number; onError?: (msg: string) => void } = {},
+  ): Promise<() => Promise<void>> {
+    const params: Record<string, unknown> = { include_reactions: false }
+    if (options.chatId !== undefined) params.chat_id = options.chatId
+    if (options.sinceRowId !== undefined) params.since_rowid = options.sinceRowId
+
+    const subscription = await this.rpc.subscribe(
+      params,
+      (raw) => onMessage(summarizeMessage(raw as ImsgMessage)),
+      options.onError,
+    )
+    return async () => {
+      await this.rpc.unsubscribe(subscription)
+    }
+  }
+
+  async getProfile(): Promise<IMessageStatus> {
+    return this.getStatus()
+  }
+
+  async close(): Promise<void> {
+    this.rpc.close()
+  }
+}

package/src/platforms/imessage/commands/auth.ts

@@ -0,0 +1,142 @@
+import { Command } from 'commander'
+
+import { handleError } from '@/shared/utils/error-handler'
+import { formatOutput } from '@/shared/utils/output'
+
+import { IMessageCredentialManager } from '../credential-manager'
+import { createAccountId } from '../types'
+
+async function guard(fn: () => Promise<void>): Promise<void> {
+  try {
+    await fn()
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+interface SetOptions {
+  bin?: string
+  region?: string
+  account?: string
+  label?: string
+  current?: boolean
+  pretty?: boolean
+  _manager?: IMessageCredentialManager
+}
+
+async function runSet(options: SetOptions): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const now = new Date().toISOString()
+  const accountId = createAccountId(options.account ?? options.label ?? options.bin ?? 'default')
+
+  await manager.setAccount({
+    account_id: accountId,
+    provider: 'imsg',
+    label: options.label,
+    binary_path: options.bin,
+    region: options.region,
+    created_at: now,
+    updated_at: now,
+  })
+  if (options.current) await manager.setCurrent(accountId)
+
+  console.log(
+    formatOutput({ success: true, account_id: accountId, binary_path: options.bin ?? 'imsg' }, options.pretty),
+  )
+  process.exit(0)
+}
+
+async function runList(options: { pretty?: boolean; _manager?: IMessageCredentialManager }): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const accounts = await manager.listAccounts()
+  console.log(
+    formatOutput(
+      accounts.map((a) => ({
+        account_id: a.account_id,
+        label: a.label,
+        binary_path: a.binary_path ?? 'imsg',
+        region: a.region,
+        is_current: a.is_current,
+      })),
+      options.pretty,
+    ),
+  )
+  process.exit(0)
+}
+
+async function runUse(
+  accountId: string,
+  options: { pretty?: boolean; _manager?: IMessageCredentialManager },
+): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const found = await manager.setCurrent(accountId)
+  if (!found) {
+    console.log(formatOutput({ error: `Account "${accountId}" not found. Run "auth list".` }, options.pretty))
+    process.exit(1)
+  }
+  console.log(formatOutput({ success: true, account_id: createAccountId(accountId) }, options.pretty))
+  process.exit(0)
+}
+
+async function runRemove(
+  accountId: string,
+  options: { pretty?: boolean; _manager?: IMessageCredentialManager },
+): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  const removed = await manager.removeAccount(accountId)
+  if (!removed) {
+    console.log(formatOutput({ error: `Account "${accountId}" not found. Run "auth list".` }, options.pretty))
+    process.exit(1)
+  }
+  console.log(formatOutput({ success: true }, options.pretty))
+  process.exit(0)
+}
+
+async function runLogout(options: { pretty?: boolean; _manager?: IMessageCredentialManager }): Promise<void> {
+  const manager = options._manager ?? new IMessageCredentialManager()
+  await manager.clearCredentials()
+  console.log(formatOutput({ success: true }, options.pretty))
+  process.exit(0)
+}
+
+export const authCommand = new Command('auth')
+  .description('Account configuration commands')
+  .addCommand(
+    new Command('set')
+      .description('Configure an iMessage account (imsg binary path / region)')
+      .option('--bin <path>', 'Path to the imsg binary (default: imsg on PATH)')
+      .option('--region <code>', 'Default region for local-format phone numbers (e.g. US)')
+      .option('--account <id>', 'Account id/alias')
+      .option('--label <label>', 'Human-friendly label')
+      .option('--current', 'Set as the active account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (opts: SetOptions) => guard(() => runSet(opts))),
+  )
+  .addCommand(
+    new Command('list')
+      .description('List configured accounts')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (opts: { pretty?: boolean }) => guard(() => runList(opts))),
+  )
+  .addCommand(
+    new Command('use')
+      .description('Switch the active account')
+      .argument('<account-id>', 'Account id')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (accountId: string, opts: { pretty?: boolean }) => guard(() => runUse(accountId, opts))),
+  )
+  .addCommand(
+    new Command('remove')
+      .description('Remove a configured account')
+      .argument('<account-id>', 'Account id')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (accountId: string, opts: { pretty?: boolean }) => guard(() => runRemove(accountId, opts))),
+  )
+  .addCommand(
+    new Command('logout')
+      .description('Clear all stored accounts')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(async (opts: { pretty?: boolean }) => guard(() => runLogout(opts))),
+  )
+
+export { runSet, runList, runUse, runRemove, runLogout }

package/src/platforms/imessage/commands/chat.ts

@@ -0,0 +1,51 @@
+import { Command } from 'commander'
+
+import { handleError } from '@/shared/utils/error-handler'
+import { formatOutput } from '@/shared/utils/output'
+
+import { parseLimitOption, withImsgClient } from './shared'
+
+async function listAction(options: { account?: string; pretty?: boolean; limit?: string }): Promise<void> {
+  try {
+    const limit = parseLimitOption(options.limit, 25)
+    const chats = await withImsgClient(options, (client) => client.listChats(limit))
+    console.log(formatOutput(chats, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+async function searchAction(
+  query: string,
+  options: { account?: string; pretty?: boolean; limit?: string },
+): Promise<void> {
+  try {
+    const limit = parseLimitOption(options.limit, 25)
+    const chats = await withImsgClient(options, (client) => client.searchChats(query, limit))
+    console.log(formatOutput(chats, options.pretty))
+    process.exit(0)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+export const chatCommand = new Command('chat')
+  .description('iMessage chat commands')
+  .addCommand(
+    new Command('list')
+      .description('List chats')
+      .option('--limit <n>', 'Number of chats to fetch', '25')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(listAction),
+  )
+  .addCommand(
+    new Command('search')
+      .description('Search chats by name or identifier')
+      .argument('<query>', 'Search query')
+      .option('--limit <n>', 'Number of results to return', '25')
+      .option('--account <id>', 'Use a specific iMessage account')
+      .option('--pretty', 'Pretty print JSON output')
+      .action(searchAction),
+  )

package/src/platforms/imessage/commands/doctor.test.ts

@@ -0,0 +1,80 @@
+import { afterEach, describe, expect, it } from 'bun:test'
+import { join } from 'node:path'
+
+import { runDoctor } from './doctor'
+
+const STUB = join(import.meta.dir, '..', 'test-stub-imsg.mjs')
+const saved: Record<string, string | undefined> = {}
+
+function setMode(mode: string, bin = STUB): void {
+  saved.IMSG_STUB_MODE = process.env.IMSG_STUB_MODE
+  saved.AGENT_IMESSAGE_BIN = process.env.AGENT_IMESSAGE_BIN
+  process.env.IMSG_STUB_MODE = mode
+  process.env.AGENT_IMESSAGE_BIN = bin
+}
+
+afterEach(() => {
+  for (const [k, v] of Object.entries(saved)) {
+    if (v === undefined) delete process.env[k]
+    else process.env[k] = v
+  }
+})
+
+describe('runDoctor', () => {
+  it('reports imsg_not_found when the binary is missing', async () => {
+    setMode('ok', '/nonexistent/imsg-xyz')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(false)
+    expect(report.code).toBe('imsg_not_found')
+    expect(report.suggestion).toContain('brew install')
+  })
+
+  it('reports full_disk_access denied with Settings guidance', async () => {
+    setMode('fda_denied')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(false)
+    expect(report.full_disk_access).toBe('denied')
+    expect(report.code).toBe('full_disk_access')
+    expect(report.suggestion).toContain('Full Disk Access')
+  })
+
+  it('reports healthy with version, FDA ok, and bridge note', async () => {
+    setMode('ok')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(true)
+    expect(report.imsg).toBe('found')
+    expect(report.imsg_version).toBe('0.11.1')
+    expect(report.full_disk_access).toBe('ok')
+    expect(report.bridge).toBe('disabled')
+    expect(report.warnings.some((w) => w.includes('Private API bridge'))).toBe(true)
+  })
+
+  it('does not mislabel a non-FDA connect failure as Full Disk Access denied', async () => {
+    setMode('connect_rpc_fail')
+    const report = await runDoctor({})
+    expect(report.ok).toBe(false)
+    expect(report.full_disk_access).toBe('unknown')
+    expect(report.code).toBe('rpc_error')
+  })
+
+  it('honors an explicit --bin override (verifies the supplied binary, not the default)', async () => {
+    setMode('ok', '/nonexistent/default-imsg')
+    const report = await runDoctor({ bin: STUB })
+    expect(report.ok).toBe(true)
+    expect(report.binary_path).toBe(STUB)
+  })
+
+  it('fails on an invalid --bin even when the default/env binary is valid', async () => {
+    setMode('ok', STUB)
+    const report = await runDoctor({ bin: '/nonexistent/custom-imsg' })
+    expect(report.ok).toBe(false)
+    expect(report.code).toBe('imsg_not_found')
+    expect(report.binary_path).toBe('/nonexistent/custom-imsg')
+  })
+
+  it('runs a test-chat send when requested', async () => {
+    setMode('ok')
+    const report = await runDoctor({ testChat: 42 })
+    expect(report.test_chat).toBe('sent')
+  })
+})

package/src/platforms/imessage/commands/doctor.ts

@@ -0,0 +1,139 @@
+import { Command } from 'commander'
+
+import { formatOutput } from '@/shared/utils/output'
+
+import { ImsgClient } from '../client'
+import { IMessageCredentialManager } from '../credential-manager'
+import { IMessageError } from '../types'
+
+export interface DoctorReport {
+  ok: boolean
+  imsg: 'found' | 'missing'
+  imsg_version?: string | null
+  binary_path: string
+  full_disk_access: 'ok' | 'denied' | 'unknown'
+  automation: string
+  bridge: 'enabled' | 'disabled'
+  test_chat?: string
+  warnings: string[]
+  error?: string
+  code?: string
+  suggestion?: string
+}
+
+export async function runDoctor(options: {
+  account?: string
+  bin?: string
+  region?: string
+  testChat?: number
+  client?: ImsgClient
+}): Promise<DoctorReport> {
+  const resolved = await new IMessageCredentialManager().resolveAccount(options.account)
+  const binaryPath = options.bin ?? resolved?.binary_path ?? process.env.AGENT_IMESSAGE_BIN ?? 'imsg'
+  const region = options.region ?? resolved?.region
+
+  const client = options.client ?? new ImsgClient()
+  await client.login({ binaryPath, region })
+
+  const warnings: string[] = []
+
+  let version: string | null = null
+  let versionError: IMessageError | undefined
+  try {
+    version = await client.getVersion()
+  } catch (error) {
+    versionError = error as IMessageError
+  }
+
+  if (version === null) {
+    const code = versionError?.code ?? 'imsg_not_found'
+    return {
+      ok: false,
+      imsg: 'missing',
+      binary_path: binaryPath,
+      full_disk_access: 'unknown',
+      automation: 'unknown',
+      bridge: 'disabled',
+      warnings,
+      error: versionError?.message ?? `Could not run "${binaryPath} --version".`,
+      code,
+      suggestion:
+        versionError?.suggestion ??
+        (code === 'imsg_not_found' ? 'Install imsg: "brew install steipete/tap/imsg".' : undefined),
+    }
+  }
+
+  let connectError: IMessageError | undefined
+  try {
+    await client.connect()
+  } catch (error) {
+    connectError = error as IMessageError
+  }
+
+  if (connectError) {
+    await client.close()
+    const isFda = connectError.code === 'full_disk_access'
+    return {
+      ok: false,
+      imsg: 'found',
+      imsg_version: version,
+      binary_path: binaryPath,
+      full_disk_access: isFda ? 'denied' : 'unknown',
+      automation: 'unknown',
+      bridge: 'disabled',
+      warnings,
+      error: connectError.message,
+      code: connectError.code,
+      suggestion:
+        connectError.suggestion ??
+        (isFda
+          ? 'Grant Full Disk Access to the app/terminal launching agent-messenger (System Settings → Privacy & Security → Full Disk Access). macOS grants to the parent process.'
+          : undefined),
+    }
+  }
+
+  warnings.push(
+    'Automation (Messages) is verified on first send. If sends fail, grant Privacy → Automation → Messages.',
+  )
+  warnings.push(
+    'Private API bridge disabled — send/read/watch/standard tapbacks work; typing/edit/group mgmt need "imsg launch" (SIP off).',
+  )
+
+  let testChatResult: string | undefined
+  if (options.testChat !== undefined) {
+    try {
+      await client.sendMessage({ chatId: options.testChat }, 'agent-imessage doctor test message')
+      testChatResult = 'sent'
+    } catch (error) {
+      testChatResult = `failed: ${(error as Error).message}`
+    }
+  }
+
+  await client.close()
+
+  return {
+    ok: true,
+    imsg: 'found',
+    imsg_version: version,
+    binary_path: binaryPath,
+    full_disk_access: 'ok',
+    automation: 'unknown',
+    bridge: 'disabled',
+    test_chat: testChatResult,
+    warnings,
+  }
+}
+
+export const doctorCommand = new Command('doctor')
+  .description('Diagnose imsg availability and macOS permissions')
+  .option('--account <id>', 'Check a specific account (default: current)')
+  .option('--bin <path>', 'Check a specific imsg binary path')
+  .option('--region <code>', 'Default region for local-format phone numbers')
+  .option('--test-chat <chatId>', 'Send a test message to this chat id')
+  .option('--pretty', 'Pretty print JSON output')
+  .action(async (opts: { account?: string; bin?: string; region?: string; testChat?: string; pretty?: boolean }) => {
+    const testChat = opts.testChat && /^\d+$/.test(opts.testChat) ? Number.parseInt(opts.testChat, 10) : undefined
+    const report = await runDoctor({ account: opts.account, bin: opts.bin, region: opts.region, testChat })
+    console.log(formatOutput(report, opts.pretty))
+    process.exit(report.ok ? 0 : 1)
+  })

package/src/platforms/imessage/commands/index.ts

@@ -0,0 +1,6 @@
+export { authCommand } from './auth'
+export { chatCommand } from './chat'
+export { doctorCommand } from './doctor'
+export { messageCommand } from './message'
+export { setupCommand } from './setup'
+export { whoamiCommand } from './whoami'

package/src/platforms/imessage/commands/message.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'bun:test'
+
+import { IMessageError } from '../types'
+import { parseRowId } from './message'
+
+describe('parseRowId', () => {
+  it('parses a non-negative integer', () => {
+    expect(parseRowId('9000')).toBe(9000)
+    expect(parseRowId('0')).toBe(0)
+  })
+
+  it('returns undefined when absent', () => {
+    expect(parseRowId(undefined)).toBeUndefined()
+  })
+
+  it('rejects non-integers', () => {
+    expect(() => parseRowId('abc')).toThrow(IMessageError)
+    expect(() => parseRowId('-5')).toThrow(IMessageError)
+  })
+})