@itm-studio/partner-sdk 0.2.9 → 0.3.0

package/README.md

@@ -103,6 +103,71 @@ export function createITMClientForRequest(request: Request) {
 
 If you also send `input.compliance`, the backend keeps the values you provide and backfills missing `ipAddress` and `userAgent` from the forwarded headers when available.
 
+### Brand Agent session authentication (first-party only)
+
+First-party ITM agents authenticate with a short-lived Brand Agent session
+instead of a partner API token. This mode is not available to external
+integrators: it requires workload identity (e.g. a Vercel OIDC token) trusted
+by the ITM backend and a backend-registered agent session, and only the
+capability-scoped operations granted to the session (`CREATE_MOMENT`,
+`SEND_EMAIL`, `READ_MOMENT_ANALYTICS`) will authorize. Everything else stays
+partner-token-only, and a request carrying both a partner API key and an
+agent session is rejected as ambiguous.
+
+```typescript
+import { createITMPartnerClient } from "@itm-studio/partner-sdk";
+
+const itm = createITMPartnerClient({
+  agentSession: {
+    // Minted fresh for every request; never cached or persisted.
+    workloadToken: () => getWorkloadOidcToken(),
+    sessionUid,
+    bootstrapToken, // optional one-time session bootstrap
+  },
+});
+```
+
+The brand is always derived server-side from the session — this mode never
+carries a brand identifier or a partner API key. Agent-session mutations must
+supply `toolCallId` on their inputs, plus `idempotencyKey` where it is not
+already required (`CreatePartnerMomentInput`; `SendPartnerAgentEmailInput`
+requires `idempotencyKey` for every caller). Partner-token callers must omit
+the agent-only fields (`toolCallId`, and `idempotencyKey` on
+`CreatePartnerMomentInput`).
+
+### Brand Agent access-token authentication (first-party only)
+
+A third mode exists for the one moment in the session lifecycle when no agent
+session exists yet: fetching a conversation thread's seed context while a new
+session is being created. It authenticates with workload identity plus the
+short-lived agent access token the caller presented, and it authorizes only
+the operations guarded for it (currently `getAgentThreadSeed`, which takes no
+arguments — the admin, brand, and thread scope all come from the token's
+verified claims).
+
+```typescript
+const itm = createITMPartnerClient({
+  agentAccess: {
+    // Minted fresh for every request; never cached or persisted.
+    workloadToken: () => getWorkloadOidcToken(),
+    // The raw bearer from the inbound session-create request.
+    accessToken,
+  },
+});
+
+const { getAgentThreadSeed } = await itm.query({
+  getAgentThreadSeed: {
+    seed: true,
+    includedMessages: true,
+    totalMessages: true,
+    truncated: true,
+  },
+});
+```
+
+Exactly one of `token`, `agentSession`, or `agentAccess` must be provided;
+combining modes is rejected.
+
 ## Money Amounts
 
 Dynamic-pricing price values use the currency's integer minor unit: cents for
@@ -236,6 +301,52 @@ basis points (`6000` = 60%). Refresh after `validUntil`. Because price is stored
 per tier, every upcoming admission window for a managed tier must fall within
 the configured horizon before that tier is eligible.
 
+## AgentMail
+
+Queue one to ten personalized plain-text emails from the authenticated brand's
+dedicated AgentMail inbox. Each item is a separate single-recipient message.
+The mutation returns after the durable batch is accepted; query the batch for
+final per-message provider status.
+
+```ts
+const queued = await client.mutation({
+  sendPartnerAgentEmail: {
+    __args: {
+      input: {
+        idempotencyKey: "venue-outreach-2026-08-13",
+        messages: [
+          {
+            to: "bookings@venue.example",
+            subject: "October show inquiry",
+            text: "Would October 10 work for a 200-person show?",
+          },
+        ],
+      },
+    },
+    uid: true,
+    status: true,
+    acceptedCount: true,
+    messages: { uid: true, recipient: true, status: true },
+  },
+});
+
+const status = await client.query({
+  getPartnerAgentEmailBatch: {
+    __args: { batchUid: queued.sendPartnerAgentEmail.uid },
+    status: true,
+    messages: {
+      recipient: true,
+      status: true,
+      agentMailMessageId: true,
+      lastErrorCode: true,
+    },
+  },
+});
+```
+
+Reuse an idempotency key only for the exact same logical batch. `SENT` means
+AgentMail accepted the message; it does not prove inbox delivery.
+
 ## Available Queries
 
 ### `getPartnerBrand`
@@ -277,7 +388,10 @@ const { getPartnerMomentsForBrand } = await itm.query({
       take: 20, // items per page (default: 50, omit to use default)
       cursor: nextCursor, // from previous response
       status: "UPCOMING", // UPCOMING | LIVE | ENDED
-      filters: { includePrivate: true }, // include private moments owned by your brand
+      filters: {
+        search: "summer launch", // case-insensitive name or slug match
+        includePrivate: true, // include private moments owned by your brand
+      },
       sortOrder: "ASC", // ASC | DESC by start date (default: DESC)
     },
     moments: { uid: true, name: true, startDate: true },
@@ -292,6 +406,9 @@ By default, only public moments are returned. Set
 `filters.includePrivate` to `true` to return both public and private moments
 owned by the brand associated with the partner token. Omitting `filters`, or
 setting `includePrivate` to `false`, preserves the public-only behavior.
+`filters.search` matches moment names and slugs case-insensitively, is limited
+to 100 characters, and composes with visibility, status, sorting, and cursor
+pagination.
 
 ### `getPartnerDrops`
 
@@ -447,9 +564,13 @@ const { getMomentLineupByToken } = await itm.query({
 
 ### `getPartnerMomentStats`
 
-Get cached partner-facing counts for a moment owned by the authenticated partner's brand.
+Get cached partner-facing counts for a moment owned by the authenticated partner's brand. Counts
+can be up to five minutes old.
 
 - `ticketsCount` counts confirmed tickets only.
+- `generatedAt` identifies when this cached count set was computed.
+- `paidTicketsCount` counts confirmed tickets with a materialized price above zero.
+- `freeTicketsCount` counts confirmed tickets with a zero materialized price.
 - `waitlistCount` counts active waitlist entries.
 - `externalRsvpCount` counts external RSVPs.
 - `ticketRsvpRequestsCount` counts ticket RSVP requests.
@@ -458,7 +579,10 @@ Get cached partner-facing counts for a moment owned by the authenticated partner
 const { getPartnerMomentStats } = await itm.query({
   getPartnerMomentStats: {
     __args: { momentSlug: "my-event-slug" },
+    generatedAt: true,
     ticketsCount: true,
+    paidTicketsCount: true,
+    freeTicketsCount: true,
     waitlistCount: true,
     externalRsvpCount: true,
     ticketRsvpRequestsCount: true,
@@ -617,6 +741,55 @@ const { getPartnerCustomersForMoment } = await itm.query({
 });
 ```
 
+### `getPartnerAudience`
+
+Get the authenticated brand's customer audience with explicit filters, one
+deterministic sort, and opaque cursor pagination. Call this only from a trusted
+Node.js server: the partner token and returned customer data must never be
+embedded in a browser/mobile bundle or written to application logs.
+
+```typescript
+const { getPartnerAudience } = await itm.query({
+  getPartnerAudience: {
+    __args: {
+      input: {
+        filters: {
+          search: "john@example.com",
+          emailConsentStatuses: ["SUBSCRIBED"],
+          momentUids: ["moment-uid"],
+          minTotalSpendUsdCents: 5000,
+        },
+        sort: { field: "TOTAL_SPEND_USD", direction: "DESC" },
+        take: 50, // maximum 100
+        includeTotalCount: true, // omitted by default to avoid the count query
+      },
+    },
+    customers: {
+      uid: true, // brand-scoped customer UID
+      name: true,
+      email: true,
+      phoneNumber: true,
+      emailConsentStatus: true,
+      smsConsentStatus: true,
+      communicationsOptedOut: true,
+      isSuppressed: true,
+      totalSpendUsdCents: true,
+      numMoments: true,
+      updatedAt: true,
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+Filters are combined with AND; values inside one list are combined with OR.
+`from` timestamps are inclusive and `before` timestamps are exclusive. Audience
+pages and optional exact counts can be up to 30 seconds old. Consent and
+suppression fields reflect ITM's current brand-scoped records but do not replace
+your legal-purpose and communications-compliance checks.
+
 ### `getPartnerMomentCollection`
 
 Get a moment collection by slug. Collections group related moments together (e.g. a summer series, a festival lineup). Returns the collection with its moments and links.