@itm-studio/partner-sdk 0.3.2 → 0.3.4

package/README.md

@@ -1879,3 +1879,37 @@ and brand ownership and records an audit entry. Partner-token callers must omit
 both audit identifiers and retain their existing upload flow.
 
 Deploy the backend media schema and migration before releasing this SDK contract.
+
+### Automatic operator CC for Eve
+
+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.

package/dist/index.d.mts

@@ -654,7 +654,12 @@ interface BrandAgentEmailSendMessage {
     lastErrorMessage: (Scalars['String'] | null);
     __typename: 'BrandAgentEmailSendMessage';
 }
+interface BrandAgentEmailContext {
+    operatorCcEmail: Scalars['String'];
+    __typename: 'BrandAgentEmailContext';
+}
 interface BrandAgentEmailSendBatch {
+    operatorCcEmail: (Scalars['String'] | null);
     uid: Scalars['String'];
     createdAt: Scalars['DateTime'];
     status: BrandAgentEmailSendBatchStatus;
@@ -681,7 +686,21 @@ interface GetPartnerMediaAssetsResponse {
     nextCursor: (Scalars['String'] | null);
     __typename: 'GetPartnerMediaAssetsResponse';
 }
+interface AgentMediaUploadReservation {
+    uid: Scalars['String'];
+    mayGenerate: Scalars['Boolean'];
+    filename: Scalars['String'];
+    uploadUrl: (Scalars['String'] | null);
+    downloadUrl: Scalars['String'];
+    uploaded: Scalars['Boolean'];
+    finishedAt: (Scalars['DateTime'] | null);
+    mediaAsset: (MediaAsset | null);
+    __typename: 'AgentMediaUploadReservation';
+}
 interface Query {
+    /** Get the authenticated agent operator email for the approval preview. Requires a brand-agent session with SEND_EMAIL; unavailable to partner API keys. */
+    getPartnerAgentEmailContext: BrandAgentEmailContext;
+    getAgentMediaUpload: AgentMediaUploadReservation;
     /** Active brand-linked assets, newest first. Defaults to 50, capped at 100. READ_MEDIA for agents. */
     getPartnerMediaAssets: GetPartnerMediaAssetsResponse;
     /** An active asset linked to the caller's brand; null when unavailable. READ_MEDIA for agents. */
@@ -803,6 +822,8 @@ interface CreatePartnerBrandSubscriptionResponse {
     __typename: 'CreatePartnerBrandSubscriptionResponse';
 }
 interface Mutation {
+    reserveAgentMediaUpload: AgentMediaUploadReservation;
+    finishAgentMediaUpload: Scalars['Boolean'];
     /**
      * Get a presigned S3 URL for direct file upload.
      * Rate limited to 30 requests per minute.
@@ -1566,7 +1587,13 @@ interface BrandAgentEmailSendMessageGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface BrandAgentEmailContextGenqlSelection {
+    operatorCcEmail?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface BrandAgentEmailSendBatchGenqlSelection {
+    operatorCcEmail?: boolean | number;
     uid?: boolean | number;
     createdAt?: boolean | number;
     status?: boolean | number;
@@ -1602,7 +1629,31 @@ interface GetPartnerMediaAssetsResponseGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface ReserveAgentMediaUploadInput {
+    idempotencyKey: Scalars['String'];
+    toolCallId: Scalars['String'];
+    requestHash: Scalars['String'];
+}
+interface AgentMediaUploadReservationGenqlSelection {
+    uid?: boolean | number;
+    mayGenerate?: boolean | number;
+    filename?: boolean | number;
+    uploadUrl?: boolean | number;
+    downloadUrl?: boolean | number;
+    uploaded?: boolean | number;
+    finishedAt?: boolean | number;
+    mediaAsset?: MediaAssetGenqlSelection;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface QueryGenqlSelection {
+    /** Get the authenticated agent operator email for the approval preview. Requires a brand-agent session with SEND_EMAIL; unavailable to partner API keys. */
+    getPartnerAgentEmailContext?: BrandAgentEmailContextGenqlSelection;
+    getAgentMediaUpload?: (AgentMediaUploadReservationGenqlSelection & {
+        __args: {
+            uid: Scalars['String'];
+        };
+    });
     /** Active brand-linked assets, newest first. Defaults to 50, capped at 100. READ_MEDIA for agents. */
     getPartnerMediaAssets?: (GetPartnerMediaAssetsResponseGenqlSelection & {
         __args: {
@@ -1790,6 +1841,8 @@ interface BrandAgentEmailMessageInput {
     text: Scalars['String'];
 }
 interface SendPartnerAgentEmailInput {
+    /** Required for agent callers: operator CC from getPartnerAgentEmailContext, shown in the approved draft. Partner callers cannot set this. */
+    operatorCcEmail?: (Scalars['String'] | null);
     /** Stable business idempotency key for this logical batch. */
     idempotencyKey: Scalars['String'];
     /** One to ten personalized, single-recipient plain-text emails. */
@@ -2078,6 +2131,16 @@ interface CreatePartnerBrandSubscriptionResponseGenqlSelection {
     __scalar?: boolean | number;
 }
 interface MutationGenqlSelection {
+    reserveAgentMediaUpload?: (AgentMediaUploadReservationGenqlSelection & {
+        __args: {
+            input: ReserveAgentMediaUploadInput;
+        };
+    });
+    finishAgentMediaUpload?: {
+        __args: {
+            uid: Scalars['String'];
+        };
+    };
     /**
      * Get a presigned S3 URL for direct file upload.
      * Rate limited to 30 requests per minute.
@@ -2101,6 +2164,7 @@ interface MutationGenqlSelection {
             idempotencyKey?: (Scalars['String'] | null);
             /** Required for agent sessions; omit for partner tokens. */
             toolCallId?: (Scalars['String'] | null);
+            reservationUid?: (Scalars['String'] | null);
         };
     });
     /**

package/dist/index.d.ts

@@ -654,7 +654,12 @@ interface BrandAgentEmailSendMessage {
     lastErrorMessage: (Scalars['String'] | null);
     __typename: 'BrandAgentEmailSendMessage';
 }
+interface BrandAgentEmailContext {
+    operatorCcEmail: Scalars['String'];
+    __typename: 'BrandAgentEmailContext';
+}
 interface BrandAgentEmailSendBatch {
+    operatorCcEmail: (Scalars['String'] | null);
     uid: Scalars['String'];
     createdAt: Scalars['DateTime'];
     status: BrandAgentEmailSendBatchStatus;
@@ -681,7 +686,21 @@ interface GetPartnerMediaAssetsResponse {
     nextCursor: (Scalars['String'] | null);
     __typename: 'GetPartnerMediaAssetsResponse';
 }
+interface AgentMediaUploadReservation {
+    uid: Scalars['String'];
+    mayGenerate: Scalars['Boolean'];
+    filename: Scalars['String'];
+    uploadUrl: (Scalars['String'] | null);
+    downloadUrl: Scalars['String'];
+    uploaded: Scalars['Boolean'];
+    finishedAt: (Scalars['DateTime'] | null);
+    mediaAsset: (MediaAsset | null);
+    __typename: 'AgentMediaUploadReservation';
+}
 interface Query {
+    /** Get the authenticated agent operator email for the approval preview. Requires a brand-agent session with SEND_EMAIL; unavailable to partner API keys. */
+    getPartnerAgentEmailContext: BrandAgentEmailContext;
+    getAgentMediaUpload: AgentMediaUploadReservation;
     /** Active brand-linked assets, newest first. Defaults to 50, capped at 100. READ_MEDIA for agents. */
     getPartnerMediaAssets: GetPartnerMediaAssetsResponse;
     /** An active asset linked to the caller's brand; null when unavailable. READ_MEDIA for agents. */
@@ -803,6 +822,8 @@ interface CreatePartnerBrandSubscriptionResponse {
     __typename: 'CreatePartnerBrandSubscriptionResponse';
 }
 interface Mutation {
+    reserveAgentMediaUpload: AgentMediaUploadReservation;
+    finishAgentMediaUpload: Scalars['Boolean'];
     /**
      * Get a presigned S3 URL for direct file upload.
      * Rate limited to 30 requests per minute.
@@ -1566,7 +1587,13 @@ interface BrandAgentEmailSendMessageGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface BrandAgentEmailContextGenqlSelection {
+    operatorCcEmail?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface BrandAgentEmailSendBatchGenqlSelection {
+    operatorCcEmail?: boolean | number;
     uid?: boolean | number;
     createdAt?: boolean | number;
     status?: boolean | number;
@@ -1602,7 +1629,31 @@ interface GetPartnerMediaAssetsResponseGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface ReserveAgentMediaUploadInput {
+    idempotencyKey: Scalars['String'];
+    toolCallId: Scalars['String'];
+    requestHash: Scalars['String'];
+}
+interface AgentMediaUploadReservationGenqlSelection {
+    uid?: boolean | number;
+    mayGenerate?: boolean | number;
+    filename?: boolean | number;
+    uploadUrl?: boolean | number;
+    downloadUrl?: boolean | number;
+    uploaded?: boolean | number;
+    finishedAt?: boolean | number;
+    mediaAsset?: MediaAssetGenqlSelection;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface QueryGenqlSelection {
+    /** Get the authenticated agent operator email for the approval preview. Requires a brand-agent session with SEND_EMAIL; unavailable to partner API keys. */
+    getPartnerAgentEmailContext?: BrandAgentEmailContextGenqlSelection;
+    getAgentMediaUpload?: (AgentMediaUploadReservationGenqlSelection & {
+        __args: {
+            uid: Scalars['String'];
+        };
+    });
     /** Active brand-linked assets, newest first. Defaults to 50, capped at 100. READ_MEDIA for agents. */
     getPartnerMediaAssets?: (GetPartnerMediaAssetsResponseGenqlSelection & {
         __args: {
@@ -1790,6 +1841,8 @@ interface BrandAgentEmailMessageInput {
     text: Scalars['String'];
 }
 interface SendPartnerAgentEmailInput {
+    /** Required for agent callers: operator CC from getPartnerAgentEmailContext, shown in the approved draft. Partner callers cannot set this. */
+    operatorCcEmail?: (Scalars['String'] | null);
     /** Stable business idempotency key for this logical batch. */
     idempotencyKey: Scalars['String'];
     /** One to ten personalized, single-recipient plain-text emails. */
@@ -2078,6 +2131,16 @@ interface CreatePartnerBrandSubscriptionResponseGenqlSelection {
     __scalar?: boolean | number;
 }
 interface MutationGenqlSelection {
+    reserveAgentMediaUpload?: (AgentMediaUploadReservationGenqlSelection & {
+        __args: {
+            input: ReserveAgentMediaUploadInput;
+        };
+    });
+    finishAgentMediaUpload?: {
+        __args: {
+            uid: Scalars['String'];
+        };
+    };
     /**
      * Get a presigned S3 URL for direct file upload.
      * Rate limited to 30 requests per minute.
@@ -2101,6 +2164,7 @@ interface MutationGenqlSelection {
             idempotencyKey?: (Scalars['String'] | null);
             /** Required for agent sessions; omit for partner tokens. */
             toolCallId?: (Scalars['String'] | null);
+            reservationUid?: (Scalars['String'] | null);
         };
     });
     /**

package/dist/index.js

@@ -1547,10 +1547,10 @@ var types_default = {
         27
       ],
       "coverImage": [
-        126
+        129
       ],
       "coverImageMobile": [
-        126
+        129
       ],
       "isActive": [
         33
@@ -2324,7 +2324,18 @@ var types_default = {
         27
       ]
     },
+    "BrandAgentEmailContext": {
+      "operatorCcEmail": [
+        27
+      ],
+      "__typename": [
+        27
+      ]
+    },
     "BrandAgentEmailSendBatch": {
+      "operatorCcEmail": [
+        27
+      ],
       "uid": [
         27
       ],
@@ -2380,7 +2391,7 @@ var types_default = {
     },
     "GetPartnerMediaAssetsResponse": {
       "mediaAssets": [
-        126
+        129
       ],
       "totalCount": [
         36
@@ -2395,18 +2406,73 @@ var types_default = {
         27
       ]
     },
+    "ReserveAgentMediaUploadInput": {
+      "idempotencyKey": [
+        27
+      ],
+      "toolCallId": [
+        27
+      ],
+      "requestHash": [
+        27
+      ],
+      "__typename": [
+        27
+      ]
+    },
+    "AgentMediaUploadReservation": {
+      "uid": [
+        27
+      ],
+      "mayGenerate": [
+        33
+      ],
+      "filename": [
+        27
+      ],
+      "uploadUrl": [
+        27
+      ],
+      "downloadUrl": [
+        27
+      ],
+      "uploaded": [
+        33
+      ],
+      "finishedAt": [
+        0
+      ],
+      "mediaAsset": [
+        129
+      ],
+      "__typename": [
+        27
+      ]
+    },
     "Query": {
+      "getPartnerAgentEmailContext": [
+        98
+      ],
+      "getAgentMediaUpload": [
+        104,
+        {
+          "uid": [
+            27,
+            "String!"
+          ]
+        }
+      ],
       "getPartnerMediaAssets": [
-        101,
+        102,
         {
           "input": [
-            100,
+            101,
             "GetPartnerMediaAssetsInput!"
           ]
         }
       ],
       "getPartnerMediaAsset": [
-        126,
+        129,
         {
           "uid": [
             27,
@@ -2418,7 +2484,7 @@ var types_default = {
         28
       ],
       "getPartnerAgentEmailBatch": [
-        98,
+        99,
         {
           "batchUid": [
             27,
@@ -2427,7 +2493,7 @@ var types_default = {
         }
       ],
       "getAgentThreadSeed": [
-        99
+        100
       ],
       "getPartnerMomentsForBrand": [
         65,
@@ -2564,7 +2630,7 @@ var types_default = {
         73,
         {
           "input": [
-            110,
+            113,
             "GetPartnerTicketTiersForMomentInput!"
           ]
         }
@@ -2573,7 +2639,7 @@ var types_default = {
         86,
         {
           "input": [
-            113,
+            116,
             "DynamicPricingMomentInput!"
           ]
         }
@@ -2644,11 +2710,14 @@ var types_default = {
       ]
     },
     "SendPartnerAgentEmailInput": {
+      "operatorCcEmail": [
+        27
+      ],
       "idempotencyKey": [
         27
       ],
       "messages": [
-        104
+        107
       ],
       "toolCallId": [
         27
@@ -2758,10 +2827,10 @@ var types_default = {
         27
       ],
       "venue": [
-        106
+        109
       ],
       "onlineConfig": [
-        108
+        111
       ],
       "isPrivate": [
         33
@@ -2776,7 +2845,7 @@ var types_default = {
         16
       ],
       "ticketTiers": [
-        107
+        110
       ],
       "idempotencyKey": [
         27
@@ -2890,7 +2959,7 @@ var types_default = {
         27
       ],
       "updates": [
-        111
+        114
       ],
       "__typename": [
         27
@@ -2921,7 +2990,7 @@ var types_default = {
         27
       ],
       "inventoryGuard": [
-        115
+        118
       ],
       "externalSignals": [
         1
@@ -2979,7 +3048,7 @@ var types_default = {
         1
       ],
       "updates": [
-        114
+        117
       ],
       "__typename": [
         27
@@ -3099,13 +3168,13 @@ var types_default = {
     },
     "PostSubscriptionMessageInput": {
       "sms": [
-        119
+        122
       ],
       "email": [
-        120
+        123
       ],
       "push": [
-        121
+        124
       ],
       "__typename": [
         27
@@ -3113,7 +3182,7 @@ var types_default = {
     },
     "CreatePartnerBrandSubscriptionInput": {
       "compliance": [
-        118
+        121
       ],
       "consentText": [
         27
@@ -3134,7 +3203,7 @@ var types_default = {
         33
       ],
       "postSubscriptionMessage": [
-        122
+        125
       ],
       "__typename": [
         27
@@ -3188,7 +3257,7 @@ var types_default = {
         27
       ],
       "transforms": [
-        127
+        130
       ],
       "createdAt": [
         0
@@ -3235,8 +3304,26 @@ var types_default = {
       ]
     },
     "Mutation": {
+      "reserveAgentMediaUpload": [
+        104,
+        {
+          "input": [
+            103,
+            "ReserveAgentMediaUploadInput!"
+          ]
+        }
+      ],
+      "finishAgentMediaUpload": [
+        33,
+        {
+          "uid": [
+            27,
+            "String!"
+          ]
+        }
+      ],
       "getPartnerUploadUrl": [
-        125,
+        128,
         {
           "filename": [
             27,
@@ -3249,7 +3336,7 @@ var types_default = {
         }
       ],
       "createPartnerMediaAsset": [
-        126,
+        129,
         {
           "mimetype": [
             27,
@@ -3260,7 +3347,7 @@ var types_default = {
             "String!"
           ],
           "dimensions": [
-            103,
+            106,
             "DimensionsInput!"
           ],
           "idempotencyKey": [
@@ -3268,14 +3355,17 @@ var types_default = {
           ],
           "toolCallId": [
             27
+          ],
+          "reservationUid": [
+            27
           ]
         }
       ],
       "createPartnerBrandSubscription": [
-        128,
+        131,
         {
           "input": [
-            123,
+            126,
             "CreatePartnerBrandSubscriptionInput!"
           ]
         }
@@ -3284,16 +3374,16 @@ var types_default = {
         38,
         {
           "input": [
-            109,
+            112,
             "CreatePartnerMomentInput!"
           ]
         }
       ],
       "sendPartnerAgentEmail": [
-        98,
+        99,
         {
           "input": [
-            105,
+            108,
             "SendPartnerAgentEmailInput!"
           ]
         }
@@ -3302,7 +3392,7 @@ var types_default = {
         72,
         {
           "input": [
-            112,
+            115,
             "EditPartnerTicketTiersForMomentInput!"
           ]
         }
@@ -3311,7 +3401,7 @@ var types_default = {
         89,
         {
           "input": [
-            116,
+            119,
             "ApplyDynamicPricingInput!"
           ]
         }
@@ -3320,7 +3410,7 @@ var types_default = {
         90,
         {
           "input": [
-            124,
+            127,
             "VerifyPartnerBrandSubscriptionInput!"
           ]
         }
@@ -3329,7 +3419,7 @@ var types_default = {
         92,
         {
           "input": [
-            117,
+            120,
             "RespondToMomentLineupInput!"
           ]
         }