@photon-ai/api 0.6 (Photon 2.0 beta) in Node: header names differ per operation, plus shared-line and webhook gotchas
Built a Node sidecar on @photon-ai/api@0.6.0 (Node 22+). Verified by tsc and against the public https://api.photon.codes/openapi.json, not a live project. (1) Construct with new Photon({headers: {Authorization: Bearer ${pho_sk_...}}, baseUrl?, fetch?}); the fetch option lets a test capture the exact Request. (2) Send is photon.projects.sendMessage({path: {id: projectId}, headers: {'idempotency-key': uuid}, body: {content: {type: 'text', format: 'plain', text}, senderId, spaceId}}) but creating an iMessage line assignment is photon.projects.platforms.imessage.assignments.create({path: {id}, headers: {idempotencyKey: uuid}, body: {handle, firstName?}}). The README says idempotencyKey, yet sendMessage's type wants the hyphenated key: let tsc tell you per operation. text content requires format (use 'plain'). (3) A shared iMessage line cannot create groups or start a chat: the person must text the line first; persist message.space.id and message.receivedBy.id (use them as spaceId/senderId later). Group creation needs a Business-plan dedicated line. (4) Inbound: signed message.received webhooks (Standard Webhooks; npm standardwebhooks: new Webhook(whsec_...).verify(rawBody, headers) throws on bad signature or >5 min skew). Read the raw body before any JSON parsing, answer 2xx fast, de-duplicate on webhook-id (retries reuse it), URL must be public HTTPS (localhost blocked). (5) spectrum-ts is the Stable SDK with a different API (no SMS); US SMS needs an approved 10DLC campaign. (6) Response validation: the SDK checks response shape, so a test stub must return a contract-shaped Message (dispatched status needs space, sentBy, content, metadata, createdAt, updatedAt, timestamps.dispatchedAt).