@itm-studio/partner-sdk 0.2.10 → 0.3.1

package/README.md

@@ -32,6 +32,8 @@ const { getPartnerMomentsForBrand } = await itm.query({
       slug: true,
       startDate: true,
       endDate: true,
+      category: true,
+      subcategory: true,
       status: true,
       timezone: true,
       externalUrl: true,
@@ -103,6 +105,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
@@ -329,7 +396,13 @@ const { getPartnerMomentsForBrand } = await itm.query({
       },
       sortOrder: "ASC", // ASC | DESC by start date (default: DESC)
     },
-    moments: { uid: true, name: true, startDate: true },
+    moments: {
+      uid: true,
+      name: true,
+      startDate: true,
+      category: true,
+      subcategory: true,
+    },
     totalCount: true,
     hasNextPage: true,
     nextCursor: true,
@@ -344,6 +417,49 @@ 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.
+Select `category` and `subcategory` on each moment when you need to filter or
+group SDK results by the event taxonomy. Both values are set when the moment
+is created; a film screening created with `category: "SCREENING"` and
+`subcategory: "FILM_SCREENING"` is returned with exactly those values.
+
+Moment tags can provide campaign-specific grouping without changing the event
+taxonomy. `momentTags` is available on every `Moment` the SDK returns, including
+`getPartnerMoment`. Only tags marked partner-visible are returned; private tags
+are never available through the SDK. Each assignment includes whether it was
+added manually or automatically. `pagination.take` must be a positive integer;
+it defaults to 50 and is capped at 100. Pass `nextCursor` back as
+`pagination.cursor` to fetch the next page:
+
+```typescript
+const { getPartnerMomentsForBrand } = await itm.query({
+  getPartnerMomentsForBrand: {
+    __args: { take: 20 },
+    moments: {
+      uid: true,
+      name: true,
+      momentTags: {
+        __args: {
+          sources: ["MANUAL"], // omit to include MANUAL and AUTO
+          pagination: { take: 50 },
+        },
+        assignments: {
+          tag: { uid: true, name: true },
+          source: true,
+          isPublic: true,
+          confidence: true,
+        },
+        totalCount: true,
+        hasNextPage: true,
+        nextCursor: true,
+      },
+    },
+    totalCount: true,
+  },
+});
+```
+
+Use the returned Moment UIDs with audience filters when you need users who
+interacted with Moments from a particular film campaign.
 
 ### `getPartnerDrops`
 
@@ -418,6 +534,11 @@ const { getPartnerMoment } = await itm.query({
       url: true,
       mimeType: true,
     },
+    venue: {
+      name: true,
+      city: true,
+      postalCode: true,
+    },
     ticketTiers: {
       name: true,
       price: true,
@@ -676,6 +797,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.
@@ -857,8 +1027,43 @@ Use OTP subscribe when you want the user to confirm the phone number before the
 - `listNames`: optional brand list names. Missing lists are created automatically and the subscribed user is attached to them.
 - `compliance`: optional metadata about how consent was collected. This is the right place for fields like `pageUrl`, `submissionMethod`, `submittedAt`, `timezone`, and geo/browser/device details.
 - `compliance.ipAddress` and `compliance.userAgent`: optional. If you omit them and forward `x-forwarded-for` and `user-agent`, the backend backfills those values for you.
+- `consentText`: optional but strongly recommended. Send the verbatim opt-in disclosure the subscriber accepted on your signup surface, up to 5000 characters. See [Marketing Consent](#marketing-consent).
 - `postSubscriptionMessage`: optional welcome message delivered automatically after the subscription becomes active. The SDK exposes this as `PostSubscriptionMessageInput` and accepts it on `CreatePartnerBrandSubscriptionInput`. See [Post-Subscription Welcome Message](#post-subscription-welcome-message).
 
+### Marketing Consent
+
+A successful subscription **is** the marketing opt-in. Once `createPartnerBrandSubscription` (or `verifyPartnerBrandSubscription` for OTP flows) returns, the subscriber is consented for the brand's marketing SMS, and for email once an address is on file. Consent flows through to the brand's connected email/SMS destinations automatically.
+
+Existing opt-outs always win, per channel. A prior STOP keyword or SMS unsubscribe for that brand blocks the SMS consent grant, and a prior email unsubscribe blocks the email consent grant — the subscription still succeeds, but consent is not granted on an opted-out channel. Users the brand has blacklisted cannot subscribe at all: the mutation fails with an authorization error.
+
+**Because the subscribe call grants consent, collect the opt-in properly on your surface:**
+
+- Show an explicit marketing consent disclosure at signup.
+- Send that exact disclosure back as `consentText`. It is stored with the subscription's compliance record as evidence of what the subscriber agreed to.
+- Send `compliance` metadata (at minimum `pageUrl` and `submissionMethod`) alongside it, and forward `x-forwarded-for` and `user-agent` so IP and user agent are captured.
+
+```typescript
+await client.mutation({
+  createPartnerBrandSubscription: {
+    __args: {
+      input: {
+        phoneNumber: "+14155551234",
+        consentText:
+          "By joining, you agree to receive recurring marketing texts from Brand. Msg & data rates may apply. Reply STOP to opt out.",
+        compliance: {
+          pageUrl: "https://example.com/signup",
+          submissionMethod: "partner_sdk",
+        },
+      },
+    },
+    subscription: { uid: true },
+    verificationRequired: true,
+  },
+});
+```
+
+`consentText` is trimmed before it is stored, and a blank value is treated as omitted. Values longer than 5000 characters are rejected with a validation error, not truncated. In OTP mode the text is captured on the first call and re-used automatically when the flow is verified — send it on the first call only.
+
 ### OTP Flow Step By Step
 
 1. Call `createPartnerBrandSubscription` with `requireOtpVerification: true`.