illusory-mapp/spec.mobile.md

Mobile Integration Spec (Stage 1)

Base URL

• Processor endpoints are mounted under /api/v1/mobile.

Headers

• Optional: x-flow-id for end-to-end trace correlation.
• Required for ping/sync endpoints: x-device-id with a previously registered externalDeviceId.

Endpoints

Register Device

• Method: POST
• Path: /api/v1/mobile/register
• Auth: none (trusted private network assumption)

Payload:

{
  "externalDeviceId": "android-1234",
  "name": "Pixel 8 Pro",
  "manufacturer": "Google",
  "model": "Pixel 8 Pro",
  "androidVersion": "15"
}

Ping Device

• Method: PUT
• Path: /api/v1/mobile/ping
• Required header: x-device-id

Payload:

{
  "pingAt": "2026-03-01T10:15:00.000Z"
}

Sync SMS

• Method: PUT
• Path: /api/v1/mobile/sms/sync
• Required header: x-device-id

Payload:

{
  "messages": [
    {
      "externalMessageId": "msg-1",
      "sender": "+358401111111",
      "recipient": "+358402222222",
      "body": "Hello from device",
      "sentAt": "2026-03-01T10:10:00.000Z",
      "receivedAt": "2026-03-01T10:10:01.000Z",
      "rawPayload": {
        "threadId": "7"
      }
    }
  ]
}

Sync Media Assets

• Method: PUT
• Path: /api/v1/mobile/media/sync
• Required header: x-device-id
• Content-Type: multipart/form-data

Upload contract:

• One request uploads one raw media file.
• Multipart field file is required (binary).
• Optional multipart metadata fields:
  • externalMediaId
  • mimeType
  • filename
  • capturedAt (ISO date string)
  • sizeBytes (number)
  • hash
  • metadata (JSON object string)
• Optional metadata headers (alternative to multipart fields):
  • x-media-external-id
  • x-media-mime-type
  • x-media-filename
  • x-media-captured-at
  • x-media-size-bytes
  • x-media-hash
  • x-media-metadata (JSON object string)

Response Contract

Success:

{
  "data": {},
  "error": null
}

Failure:

{
  "data": null,
  "error": {
    "flowId": "uuid",
    "code": "VALIDATION_ERROR",
    "message": "Human message",
    "description": "Actionable description",
    "detail": "Technical detail"
  }
}

Admin Query Contract

• Pagination:
  • page: 1-based integer
  • pageSize: integer
• Sorting:
  • sortBy: operation-specific
  • sortOrder: asc or desc
• Paginated response payload:
  • data: rows
  • total: full row count
  • page, pageSize, totalPages

Dedup Rules

• Device:
  • Upsert on unique externalDeviceId.
• SMS:
  • Dedup key #1: (deviceId, externalMessageId) when provided.
  • Dedup key #2 fallback: (deviceId, dedupHash) where dedup hash is SHA-256 of (deviceId + sentAt + sender + body).
• Media:
  • Raw file is uploaded first and persisted in file.
  • Then one mobile_media_asset row is created referencing uploaded fileId.
  • Dedup key: (deviceId, externalMediaId) when provided.

Operator Checklist

1. Register a device.
2. Send ping with x-device-id and verify dashboard lastPingAt updates.
3. Sync SMS and verify device detail SMS tab updates (polling every 5s).
4. Sync media and verify device detail Media Assets tab displays rows.