fix(integrations): address second round of Photon iMessage review

The 409 re-key branch no longer discards the outcome of the steps it depends
on. Re-registering over a stale record that is still there just earns another
409, so a failed listing or a failed DELETE now surfaces as the thing an
operator can act on — delete the webhook in the Photon dashboard and redeploy —
instead of a second conflict with no explanation.

One content walker, not two. `extractText` claimed to mirror the webhook's
`collectText` but returned only a group's first text node and counted an empty
string as a hit, so Get Message and the trigger could report different `text`
for the same grouped delivery. Both surfaces now read through
`@/lib/photon-imessage/content`. Sharing it also settles the attachment shape:
absent fields are `null` on both sides rather than `null` on one and `''` on
the other. This is the third bug from these two copies drifting, so the copies
are gone rather than re-aligned.

Media file inputs are required for `send_media` and `send_voice_memo`, matching
Linq's attachment pattern, so the editor catches a missing file instead of
letting the run fail on a route 400. The clearable ops keep an optional file —
`imageAction: 'clear'` is a valid way to run those without one. Both members of
the canonical pair carry the same condition, as the group requires.

Also converts the `messageEffects` declaration comment to TSDoc.

Adds 24 tests: the walkers' group/reply/voice handling and the parity the
shared module exists to guarantee, plus both new 409-recovery failure paths.

Author: qwerzl

apps/sim/app/api/tools/photon_imessage/utils.ts

@@ -22,9 +22,16 @@ import {
 } from '@spectrum-ts/core'
 import { effect, imessage } from '@spectrum-ts/imessage'
 import { LRUCache } from 'lru-cache'
+import {
+  collectPhotonAttachments,
+  collectPhotonText,
+  type PhotonAttachmentSummary,
+} from '@/lib/photon-imessage/content'
 
-// Apple effect identifiers keyed by friendly name (balloons, confetti, slam, …), exposed as a
-// static on the provider callable.
+/**
+ * Apple effect identifiers keyed by friendly name (balloons, confetti, slam, …), exposed as a
+ * static on the provider callable.
+ */
 const messageEffects = imessage.effect.message
 
 const logger = createLogger('PhotonImessageClient')
@@ -458,13 +465,6 @@ export async function createPhotonGroup(
   })
 }
 
-export interface PhotonAttachmentSummary {
-  id: string | null
-  name: string | null
-  mimeType: string | null
-  size: number | null
-}
-
 export interface PhotonMessageDetails {
   messageId: string
   chatId: string
@@ -475,59 +475,6 @@ export interface PhotonMessageDetails {
   attachments: PhotonAttachmentSummary[]
 }
 
-/** Depth-first text extraction through reply/group wrappers, mirroring the webhook handler. */
-function extractText(content: unknown): string | null {
-  if (!content || typeof content !== 'object') {
-    return null
-  }
-  const node = content as Record<string, unknown>
-  if (node.type === 'text' && typeof node.text === 'string') {
-    return node.text
-  }
-  if (node.type === 'reply') {
-    return extractText(node.content)
-  }
-  if (node.type === 'group' && Array.isArray(node.items)) {
-    for (const item of node.items) {
-      const found = extractText((item as Record<string, unknown>).content ?? item)
-      if (found !== null) {
-        return found
-      }
-    }
-  }
-  return null
-}
-
-/**
- * Attachment metadata, mirroring `collectAttachments` in the webhook handler. A native voice memo
- * is a distinct content arm carrying the same id/name/mimeType, so both feed Download Attachment.
- */
-function extractAttachments(content: unknown): PhotonAttachmentSummary[] {
-  if (!content || typeof content !== 'object') {
-    return []
-  }
-  const node = content as Record<string, unknown>
-  if (node.type === 'attachment' || node.type === 'voice') {
-    return [
-      {
-        id: typeof node.id === 'string' ? node.id : null,
-        name: typeof node.name === 'string' ? node.name : null,
-        mimeType: typeof node.mimeType === 'string' ? node.mimeType : null,
-        size: typeof node.size === 'number' ? node.size : null,
-      },
-    ]
-  }
-  if (node.type === 'reply') {
-    return extractAttachments(node.content)
-  }
-  if (node.type === 'group' && Array.isArray(node.items)) {
-    return node.items.flatMap((item) =>
-      extractAttachments((item as Record<string, unknown>).content ?? item)
-    )
-  }
-  return []
-}
-
 export async function getPhotonMessage(
   params: PhotonCredentials & {
     chatId: string
@@ -541,11 +488,12 @@ export async function getPhotonMessage(
     return {
       messageId: message.id,
       chatId: space.id,
-      text: extractText(message.content),
+      // `''` from the shared walker means "no text"; this surface reports that as null.
+      text: collectPhotonText(message.content) || null,
       contentType: message.content?.type ?? 'unknown',
       senderId: message.sender?.id ?? null,
       timestamp: message.timestamp?.toISOString() ?? null,
-      attachments: extractAttachments(message.content),
+      attachments: collectPhotonAttachments(message.content),
     }
   })
 }

apps/sim/blocks/blocks/photon_imessage.ts

@@ -50,6 +50,12 @@ const FILE_OPS = [
 
 const CLEARABLE_OPS = ['set_group_avatar', 'set_chat_background'] as const
 
+/**
+ * File operations with no alternative to sending bytes. The clearable ops are excluded because
+ * `imageAction: 'clear'` is a valid way to run them without a file.
+ */
+const FILE_REQUIRED_OPS = ['send_media', 'send_voice_memo'] as const
+
 const PARTICIPANT_OPS = ['add_participant', 'remove_participant'] as const
 
 const splitHandles = (value: unknown): string[] =>
@@ -386,6 +392,7 @@ export const PhotonImessageBlock: BlockConfig = {
       placeholder: 'Upload a file (max 100MB)',
       multiple: false,
       condition: { field: 'operation', value: [...FILE_OPS] },
+      required: { field: 'operation', value: [...FILE_REQUIRED_OPS] },
       mode: 'basic',
     },
     {
@@ -395,6 +402,7 @@ export const PhotonImessageBlock: BlockConfig = {
       canonicalParamId: 'file',
       placeholder: 'Reference a file from a previous block (e.g. {{block.output.file}})',
       condition: { field: 'operation', value: [...FILE_OPS] },
+      required: { field: 'operation', value: [...FILE_REQUIRED_OPS] },
       mode: 'advanced',
     },
     {

apps/sim/lib/photon-imessage/content.test.ts

@@ -0,0 +1,132 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { collectPhotonAttachments, collectPhotonText } from '@/lib/photon-imessage/content'
+
+const attachmentNode = {
+  type: 'attachment',
+  id: 'att-1',
+  name: 'photo.jpg',
+  mimeType: 'image/jpeg',
+  size: 2048,
+}
+
+const voiceNode = { type: 'voice', id: 'voice-1', mimeType: 'audio/x-caf' }
+
+describe('collectPhotonText', () => {
+  it('reads a plain text node', () => {
+    expect(collectPhotonText({ type: 'text', text: 'hello there' })).toBe('hello there')
+  })
+
+  it('reaches through a reply wrapper to the inner content', () => {
+    expect(
+      collectPhotonText({
+        type: 'reply',
+        content: { type: 'text', text: 'replying to you' },
+        target: { id: 'msg-1' },
+      })
+    ).toBe('replying to you')
+  })
+
+  it('joins every text in a group rather than stopping at the first', () => {
+    expect(
+      collectPhotonText({
+        type: 'group',
+        items: [
+          { content: { type: 'text', text: 'first' } },
+          { content: attachmentNode },
+          { content: { type: 'text', text: 'second' } },
+        ],
+      })
+    ).toBe('first\nsecond')
+  })
+
+  it('skips an empty text in a group instead of treating it as the answer', () => {
+    expect(
+      collectPhotonText({
+        type: 'group',
+        items: [
+          { content: { type: 'text', text: '' } },
+          { content: { type: 'text', text: 'the real message' } },
+        ],
+      })
+    ).toBe('the real message')
+  })
+
+  it('accepts a group item that is the content node itself', () => {
+    expect(collectPhotonText({ type: 'group', items: [{ type: 'text', text: 'unwrapped' }] })).toBe(
+      'unwrapped'
+    )
+  })
+
+  it('returns an empty string for content that carries no text', () => {
+    expect(collectPhotonText(attachmentNode)).toBe('')
+    expect(collectPhotonText({ type: 'reaction', emoji: '❤️' })).toBe('')
+    expect(collectPhotonText(null)).toBe('')
+    expect(collectPhotonText('not a node')).toBe('')
+  })
+})
+
+describe('collectPhotonAttachments', () => {
+  it('summarizes an attachment node', () => {
+    expect(collectPhotonAttachments(attachmentNode)).toEqual([
+      { id: 'att-1', name: 'photo.jpg', mimeType: 'image/jpeg', size: 2048 },
+    ])
+  })
+
+  it('treats a native voice memo as an attachment, nulling the fields it omits', () => {
+    expect(collectPhotonAttachments(voiceNode)).toEqual([
+      { id: 'voice-1', name: null, mimeType: 'audio/x-caf', size: null },
+    ])
+  })
+
+  it('collects every media node in a group, through a reply wrapper', () => {
+    expect(
+      collectPhotonAttachments({
+        type: 'reply',
+        content: {
+          type: 'group',
+          items: [
+            { content: { type: 'text', text: 'look' } },
+            { content: attachmentNode },
+            { content: voiceNode },
+          ],
+        },
+      }).map((attachment) => attachment.id)
+    ).toEqual(['att-1', 'voice-1'])
+  })
+
+  it('returns nothing for content that carries no media', () => {
+    expect(collectPhotonAttachments({ type: 'text', text: 'hi' })).toEqual([])
+    expect(collectPhotonAttachments(null)).toEqual([])
+  })
+})
+
+describe('surface parity', () => {
+  /**
+   * The webhook handler and the Get Message tool both read a message through these walkers, so a
+   * grouped delivery reports identically on either — the drift this module exists to prevent.
+   */
+  it('reports one grouped message the same way for both readers', () => {
+    const grouped = {
+      type: 'group',
+      items: [
+        { content: { type: 'text', text: 'caption one' } },
+        { content: attachmentNode },
+        { content: { type: 'text', text: 'caption two' } },
+        { content: voiceNode },
+      ],
+    }
+
+    const triggerText = collectPhotonText(grouped)
+    const toolText = collectPhotonText(grouped) || null
+
+    expect(triggerText).toBe('caption one\ncaption two')
+    expect(toolText).toBe(triggerText)
+    expect(collectPhotonAttachments(grouped)).toEqual([
+      { id: 'att-1', name: 'photo.jpg', mimeType: 'image/jpeg', size: 2048 },
+      { id: 'voice-1', name: null, mimeType: 'audio/x-caf', size: null },
+    ])
+  })
+})

apps/sim/lib/photon-imessage/content.ts

@@ -0,0 +1,86 @@
+import { isRecordLike } from '@sim/utils/object'
+
+/**
+ * Walkers over Photon's slim content tree.
+ *
+ * Two surfaces read the same message: the webhook handler, which builds trigger outputs, and the
+ * Get Message tool. A workflow that reads `text` or `attachments` must see the same thing from
+ * either, so there is one implementation rather than a copy per surface with a comment asking the
+ * next reader to keep them aligned.
+ */
+
+export interface PhotonAttachmentSummary {
+  id: string | null
+  name: string | null
+  mimeType: string | null
+  size: number | null
+}
+
+const asNullableString = (value: unknown): string | null =>
+  typeof value === 'string' ? value : null
+
+/** A group item is either a `{ content }` wrapper or the content node itself. */
+const itemContent = (item: Record<string, unknown>): unknown => item.content ?? item
+
+/**
+ * The human-readable text of a content tree. A reply carries its own inner content and a group
+ * carries N items, so the text a workflow wants is not always at the top level. Every non-empty
+ * text in a group contributes, joined by newlines; `''` means the message carries no text.
+ */
+export function collectPhotonText(content: unknown): string {
+  if (!isRecordLike(content)) {
+    return ''
+  }
+
+  switch (content.type) {
+    case 'text':
+      return typeof content.text === 'string' ? content.text : ''
+    case 'reply':
+      return collectPhotonText(content.content)
+    case 'group': {
+      const items = Array.isArray(content.items) ? content.items : []
+      return items
+        .map((item) => (isRecordLike(item) ? collectPhotonText(itemContent(item)) : ''))
+        .filter(Boolean)
+        .join('\n')
+    }
+    default:
+      return ''
+  }
+}
+
+/**
+ * Attachment metadata for every media node in a content tree. A native voice memo is its own
+ * content arm carrying the same id/name/mimeType, and both feed the Download Attachment operation.
+ *
+ * Only metadata: bytes stay behind the platform and are fetched on demand, which a webhook payload
+ * cannot do.
+ */
+export function collectPhotonAttachments(content: unknown): PhotonAttachmentSummary[] {
+  if (!isRecordLike(content)) {
+    return []
+  }
+
+  switch (content.type) {
+    case 'attachment':
+    case 'voice':
+      return [
+        {
+          id: asNullableString(content.id),
+          name: asNullableString(content.name),
+          mimeType: asNullableString(content.mimeType),
+          size: typeof content.size === 'number' ? content.size : null,
+        },
+      ]
+    case 'reply':
+      return collectPhotonAttachments(content.content)
+    case 'group': {
+      const items = Array.isArray(content.items) ? content.items : []
+      return items.flatMap((item) =>
+        isRecordLike(item) ? collectPhotonAttachments(itemContent(item)) : []
+      )
+    }
+    default:
+      return []
+  }
+}