feat(integrations): add iMessage via Photon

Adds an iMessage integration backed by Photon (spectrum-ts), covering both
directions: a send tool and a signed webhook trigger for inbound messages.

Photon reaches iMessage over gRPC through the @spectrum-ts/imessage SDK rather
than a plain REST call, so the send runs in an internal route. Spectrum
instances are cached per project and evicted LRU, because constructing one
mints cloud credentials and opens a connection per line.

Inbound deliveries are verified with Photon's own portable verifier
(@spectrum-ts/core/webhook), which implements the documented v0 scheme:
HMAC-SHA256 over "v0:<timestamp>:<rawBody>" with a 5-minute replay window.
Verification fails closed when no secret is configured — an inbound message can
drive an agent, so an unverified delivery must never reach one. Deliveries are
at-least-once, so runs are deduped on the message id.

Payload mapping is taken from the SlimEnvelope schema in photon-hq/spectrum-ts
rather than inferred, and a test asserts formatInput's keys match the trigger
outputs exactly.

Author: qwerzl

apps/docs/components/icons.tsx

@@ -1042,6 +1042,17 @@ export function PerplexityIcon(props: SVGProps<SVGSVGElement>) {
   )
 }
 
+export function PhotonIcon(props: SVGProps<SVGSVGElement>) {
+  return (
+    <svg width='1em' height='1em' viewBox='2 5 24 24' xmlns='http://www.w3.org/2000/svg' {...props}>
+      <path
+        d='M21.56 18.452H24.192C24.668 18.452 25.004 18.9 24.892 19.32L22.876 27.328C22.82 27.636 22.54 27.86 22.204 27.86H19.544C19.124 27.86 18.788 27.412 18.872 26.992L20.888 18.984C20.972 18.676 21.224 18.452 21.56 18.452ZM16.24 6.02H18.872C19.348 6.02 19.684 6.468 19.544 6.888L17.584 14.896C17.472 15.204 17.192 15.428 16.856 15.428H14.252C13.776 15.428 13.44 14.98 13.58 14.56L15.568 6.552C15.624 6.244 15.932 6.02 16.24 6.02ZM5.712 11.788H8.344C8.792 11.788 9.128 12.236 9.016 12.684L7.028 20.664C6.944 20.972 6.664 21.196 6.356 21.196H3.696C3.248 21.196 2.884 20.776 3.024 20.328L5.012 12.348C5.096 12.012 5.376 11.788 5.712 11.788Z'
+        fill='currentColor'
+      />
+    </svg>
+  )
+}
+
 export function ObsidianIcon(props: SVGProps<SVGSVGElement>) {
   const id = useId()
   const bl = `${id}-bl`

apps/docs/components/ui/icon-mapping.ts

@@ -179,6 +179,7 @@ import {
   PeopleDataLabsIcon,
   PerplexityIcon,
   PersonaIcon,
+  PhotonIcon,
   PineconeIcon,
   PipedriveIcon,
   PitchBookIcon,
@@ -475,6 +476,7 @@ export const blockTypeToIconMap: Record<string, IconComponent> = {
   peopledatalabs: PeopleDataLabsIcon,
   perplexity: PerplexityIcon,
   persona: PersonaIcon,
+  photon_imessage: PhotonIcon,
   pinecone: PineconeIcon,
   pipedrive: PipedriveIcon,
   pitchbook: PitchBookIcon,

apps/docs/content/docs/en/integrations/meta.json

@@ -190,6 +190,7 @@
     "peopledatalabs",
     "perplexity",
     "persona",
+    "photon_imessage",
     "pinecone",
     "pipedrive",
     "pipedrive-service-account",

apps/docs/content/docs/en/integrations/photon_imessage.mdx

@@ -0,0 +1,43 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { photonImessageAddParticipantContract } from '@/lib/api/contracts/tools/photon-imessage'
+import { parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { addPhotonParticipant } from '@/app/api/tools/photon_imessage/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('PhotonImessageAddParticipantAPI')
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success) {
+      logger.warn(`[${requestId}] Unauthorized Photon participant add attempt: ${authResult.error}`)
+      return NextResponse.json(
+        { success: false, error: authResult.error || 'Authentication required' },
+        { status: 401 }
+      )
+    }
+
+    const parsed = await parseRequest(photonImessageAddParticipantContract, request, {})
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
+
+    const output = await addPhotonParticipant({ ...body })
+    return NextResponse.json({ success: true, output })
+  } catch (error) {
+    const errorMessage = getErrorMessage(error, 'Unknown error occurred')
+    logger.error(`[${requestId}] Photon participant add failed:`, error)
+
+    return NextResponse.json(
+      { success: false, error: `Photon participant add failed: ${errorMessage}` },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/tools/photon_imessage/add-participant/route.ts

@@ -0,0 +1,66 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { photonImessageChatBackgroundContract } from '@/lib/api/contracts/tools/photon-imessage'
+import { parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { materializePhotonFile } from '@/app/api/tools/photon_imessage/route-helpers'
+import { setPhotonChatBackground } from '@/app/api/tools/photon_imessage/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('PhotonImessageChatBackgroundAPI')
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success) {
+      logger.warn(
+        `[${requestId}] Unauthorized Photon chat background update attempt: ${authResult.error}`
+      )
+      return NextResponse.json(
+        { success: false, error: authResult.error || 'Authentication required' },
+        { status: 401 }
+      )
+    }
+
+    const parsed = await parseRequest(photonImessageChatBackgroundContract, request, {})
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
+
+    if (body.clear) {
+      const output = await setPhotonChatBackground({
+        projectId: body.projectId,
+        projectSecret: body.projectSecret,
+        to: body.to,
+        clear: true,
+      })
+      return NextResponse.json({ success: true, output })
+    }
+
+    const file = await materializePhotonFile(body, { requestId, userId: authResult.userId })
+    if (file instanceof NextResponse) return file
+
+    const output = await setPhotonChatBackground({
+      projectId: body.projectId,
+      projectSecret: body.projectSecret,
+      to: body.to,
+      fileBuffer: file.buffer,
+      fileName: file.fileName,
+      mimeType: file.mimeType,
+    })
+    return NextResponse.json({ success: true, output })
+  } catch (error) {
+    const errorMessage = getErrorMessage(error, 'Unknown error occurred')
+    logger.error(`[${requestId}] Photon chat background update failed:`, error)
+
+    return NextResponse.json(
+      { success: false, error: `Photon chat background update failed: ${errorMessage}` },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/tools/photon_imessage/chat-background/route.ts

@@ -0,0 +1,43 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { photonImessageCreateGroupContract } from '@/lib/api/contracts/tools/photon-imessage'
+import { parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { createPhotonGroup } from '@/app/api/tools/photon_imessage/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('PhotonImessageCreateGroupAPI')
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success) {
+      logger.warn(`[${requestId}] Unauthorized Photon group creation attempt: ${authResult.error}`)
+      return NextResponse.json(
+        { success: false, error: authResult.error || 'Authentication required' },
+        { status: 401 }
+      )
+    }
+
+    const parsed = await parseRequest(photonImessageCreateGroupContract, request, {})
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
+
+    const output = await createPhotonGroup({ ...body })
+    return NextResponse.json({ success: true, output })
+  } catch (error) {
+    const errorMessage = getErrorMessage(error, 'Unknown error occurred')
+    logger.error(`[${requestId}] Photon group creation failed:`, error)
+
+    return NextResponse.json(
+      { success: false, error: `Photon group creation failed: ${errorMessage}` },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/tools/photon_imessage/create-group/route.ts

@@ -0,0 +1,43 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { photonImessageCreatePollContract } from '@/lib/api/contracts/tools/photon-imessage'
+import { parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { createPhotonPoll } from '@/app/api/tools/photon_imessage/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('PhotonImessageCreatePollAPI')
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success) {
+      logger.warn(`[${requestId}] Unauthorized Photon poll creation attempt: ${authResult.error}`)
+      return NextResponse.json(
+        { success: false, error: authResult.error || 'Authentication required' },
+        { status: 401 }
+      )
+    }
+
+    const parsed = await parseRequest(photonImessageCreatePollContract, request, {})
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
+
+    const output = await createPhotonPoll({ ...body })
+    return NextResponse.json({ success: true, output })
+  } catch (error) {
+    const errorMessage = getErrorMessage(error, 'Unknown error occurred')
+    logger.error(`[${requestId}] Photon poll creation failed:`, error)
+
+    return NextResponse.json(
+      { success: false, error: `Photon poll creation failed: ${errorMessage}` },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/tools/photon_imessage/create-poll/route.ts

@@ -0,0 +1,45 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { photonImessageDownloadAttachmentContract } from '@/lib/api/contracts/tools/photon-imessage'
+import { parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { downloadPhotonAttachment } from '@/app/api/tools/photon_imessage/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('PhotonImessageDownloadAttachmentAPI')
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success) {
+      logger.warn(
+        `[${requestId}] Unauthorized Photon attachment download attempt: ${authResult.error}`
+      )
+      return NextResponse.json(
+        { success: false, error: authResult.error || 'Authentication required' },
+        { status: 401 }
+      )
+    }
+
+    const parsed = await parseRequest(photonImessageDownloadAttachmentContract, request, {})
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
+
+    const output = await downloadPhotonAttachment({ ...body })
+    return NextResponse.json({ success: true, output })
+  } catch (error) {
+    const errorMessage = getErrorMessage(error, 'Unknown error occurred')
+    logger.error(`[${requestId}] Photon attachment download failed:`, error)
+
+    return NextResponse.json(
+      { success: false, error: `Photon attachment download failed: ${errorMessage}` },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/tools/photon_imessage/download-attachment/route.ts

@@ -0,0 +1,43 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { photonImessageEditContract } from '@/lib/api/contracts/tools/photon-imessage'
+import { parseRequest } from '@/lib/api/server'
+import { checkInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { editPhotonMessage } from '@/app/api/tools/photon_imessage/utils'
+
+export const dynamic = 'force-dynamic'
+
+const logger = createLogger('PhotonImessageEditAPI')
+
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  try {
+    const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success) {
+      logger.warn(`[${requestId}] Unauthorized Photon message edit attempt: ${authResult.error}`)
+      return NextResponse.json(
+        { success: false, error: authResult.error || 'Authentication required' },
+        { status: 401 }
+      )
+    }
+
+    const parsed = await parseRequest(photonImessageEditContract, request, {})
+    if (!parsed.success) return parsed.response
+    const body = parsed.data.body
+
+    const output = await editPhotonMessage({ ...body })
+    return NextResponse.json({ success: true, output })
+  } catch (error) {
+    const errorMessage = getErrorMessage(error, 'Unknown error occurred')
+    logger.error(`[${requestId}] Photon message edit failed:`, error)
+
+    return NextResponse.json(
+      { success: false, error: `Photon message edit failed: ${errorMessage}` },
+      { status: 500 }
+    )
+  }
+})