@itm-studio/partner-sdk 0.3.3 → 0.3.5

package/README.md

@@ -1885,3 +1885,31 @@ Deploy the backend media schema and migration before releasing this SDK contract
 Agent-session email callers first query `getPartnerAgentEmailContext { operatorCcEmail }`, show that address with every email draft, and include `operatorCcEmail` in `SendPartnerAgentEmailInput` after approval. The backend verifies it against the authenticated admin, snapshots it on the batch, and CCs that address on each message. When the operator is already the primary recipient, no duplicate CC is added. Read the approved snapshot through `BrandAgentEmailSendBatch.operatorCcEmail`. A changed operator address before queuing requires a revised draft and approval; queued retries retain the original address.
 
 Partner API-key callers cannot query operator context or supply operator CC. Existing partner sends and the brand Reply-To address retain their existing behavior.
+
+### Agent-generated posters
+
+Agent sessions with `UPLOAD_MEDIA` can reserve an immutable upload using
+`reserveAgentMediaUpload({ input: { idempotencyKey, toolCallId, requestHash } })`.
+The request hash is SHA-256 of the canonical generation brief and model settings.
+Only the first claim receives `mayGenerate: true`; replays must inspect
+`getAgentMediaUpload({ uid })` and must never repeat a paid generation.
+
+Generate pixels inside Eve through AI Gateway. PUT the PNG to the reserved
+`uploadUrl` with `Content-Type: image/png` and `If-None-Match: *`. Keep signed URLs
+and image bytes out of chat/tool results. Reserved posters are 1024 × 1280 PNGs,
+up to 10 MB. Register through `createPartnerMediaAsset` with the reservation's
+`filename`, `reservationUid`, `idempotencyKey: "media-upload:" + reservation.uid`,
+and the current `toolCallId`. Registration links the resulting asset to brand media.
+Return its UID, URL, MIME type and dimensions for preview and moment selection.
+
+`getAgentMediaUpload` returns an existing asset or reports whether the object was
+uploaded, allowing registration after interruption without another model call.
+`finishAgentMediaUpload({ uid })` releases an unsuccessful attempt's active slot;
+it never grants permission to regenerate that attempt. A brand allows one active
+attempt for five minutes. Recovery requires the original brand and admin identity
+with current authorization; partner API keys cannot use reservation operations.
+Each requested revision gets a new reservation and brand media asset.
+
+Deploy the backend reservation migration and schema before publishing SDK 0.3.3,
+then release the Eve and Backstage consumers. These operations do not call an
+image provider or consume notification credits.