@itm-studio/partner-sdk 0.2.6 → 0.2.8

package/README.md

@@ -16,7 +16,7 @@ npm install @itm-studio/partner-sdk
 ## Quick Start
 
 ```typescript
-import { createITMPartnerClient } from '@itm-studio/partner-sdk';
+import { createITMPartnerClient } from "@itm-studio/partner-sdk";
 
 const itm = createITMPartnerClient({
   token: process.env.ITM_PARTNER_TOKEN!,
@@ -25,7 +25,7 @@ const itm = createITMPartnerClient({
 // Get all upcoming moments for your brand
 const { getPartnerMomentsForBrand } = await itm.query({
   getPartnerMomentsForBrand: {
-    __args: { status: 'UPCOMING', take: 10 },
+    __args: { status: "UPCOMING", take: 10 },
     moments: {
       uid: true,
       name: true,
@@ -70,18 +70,18 @@ Keep the partner token on your server. Do not expose it from browser code or cli
 For request-scoped mutations such as partner brand subscriptions, create the client inside the incoming request and forward `x-forwarded-for` and `user-agent` so the backend can enrich compliance metadata when those fields are omitted from `input.compliance`.
 
 ```typescript
-import { createITMPartnerClient } from '@itm-studio/partner-sdk';
+import { createITMPartnerClient } from "@itm-studio/partner-sdk";
 
 export function createITMClientForRequest(request: Request) {
   return createITMPartnerClient({
     token: process.env.ITM_PARTNER_TOKEN!,
     headers: () => {
-      const forwardedFor = request.headers.get('x-forwarded-for');
-      const userAgent = request.headers.get('user-agent');
+      const forwardedFor = request.headers.get("x-forwarded-for");
+      const userAgent = request.headers.get("user-agent");
 
       return {
-        ...(forwardedFor ? { 'x-forwarded-for': forwardedFor } : {}),
-        ...(userAgent ? { 'user-agent': userAgent } : {}),
+        ...(forwardedFor ? { "x-forwarded-for": forwardedFor } : {}),
+        ...(userAgent ? { "user-agent": userAgent } : {}),
       };
     },
   });
@@ -92,21 +92,41 @@ If you also send `input.compliance`, the backend keeps the values you provide an
 
 ## Money Amounts
 
-Partner API price values are always encoded as `amount * 100`. Divide by `100` before rendering a major-unit display amount (dollars for USD, euros for EUR, yen for JPY, etc.).
-
-This convention also applies to zero-decimal currencies such as JPY and KRW. The rendering conversion is always `price / 100`; zero-decimal status only controls whether the formatted display shows fractional digits. For example, `2500` should be displayed as `JPY 25`, not `JPY 2,500`.
+Dynamic-pricing price values use the currency's integer minor unit: cents for
+USD and EUR, and whole units for zero-decimal currencies such as JPY and KRW.
+Do not multiply zero-decimal dynamic-pricing amounts by 100. Older partner tier
+read/edit fields retain the backend's historical cents representation; use the
+dynamic-pricing API for price changes on enrolled tiers.
 
 ```typescript
-const ZERO_DECIMAL_CURRENCIES = new Set(['BIF', 'CLP', 'DJF', 'GNF', 'JPY', 'KMF', 'KRW', 'MGA', 'PYG', 'RWF', 'UGX', 'VND', 'VUV', 'XAF', 'XOF', 'XPF']);
-
-function formatPartnerPrice(priceInCents: number, currencyCode: string) {
-  if (priceInCents === 0) return 'Free';
-
-  const amount = priceInCents / 100;
-  const maximumFractionDigits = ZERO_DECIMAL_CURRENCIES.has(currencyCode) ? 0 : 2;
-
-  return new Intl.NumberFormat('en-US', {
-    style: 'currency',
+const ZERO_DECIMAL_CURRENCIES = new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "JPY",
+  "KMF",
+  "KRW",
+  "MGA",
+  "PYG",
+  "RWF",
+  "UGX",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF",
+]);
+
+function formatPartnerPrice(priceInMinorUnits: number, currencyCode: string) {
+  if (priceInMinorUnits === 0) return "Free";
+
+  const zeroDecimal = ZERO_DECIMAL_CURRENCIES.has(currencyCode);
+  const amount = zeroDecimal ? priceInMinorUnits : priceInMinorUnits / 100;
+  const maximumFractionDigits = zeroDecimal ? 0 : 2;
+
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
     currency: currencyCode,
     minimumFractionDigits: maximumFractionDigits,
     maximumFractionDigits,
@@ -114,8 +134,125 @@ function formatPartnerPrice(priceInCents: number, currencyCode: string) {
 }
 ```
 
+## Dynamic Pricing
+
+Dynamic pricing is a controlled actuator, not a hosted rules engine. A brand
+admin first enables a moment policy and enrolls paid tiers with minimum and
+maximum prices. The partner then reads current context and explicitly chooses
+which enrolled tiers to update.
+
+Always fetch fresh context immediately before an apply. Admission windows,
+policy version, bounds, configured supply, and current price form the stable
+pricing concurrency contract. Live sales do not invalidate
+`pricingContextVersion`. Each update must separately declare whether it is
+inventory-independent or provide a remaining-supply/fill-rate range checked
+under the price-write lock. The entire batch is atomic.
+
+```typescript
+const { getPartnerMomentDynamicPricingContext: context } = await itm.query({
+  getPartnerMomentDynamicPricingContext: {
+    __args: { input: { momentUid } },
+    policy: { version: true, enabled: true },
+    tiers: {
+      ticketTierUid: true,
+      currentPrice: true,
+      minPrice: true,
+      maxPrice: true,
+      eligible: true,
+      pricingContextVersion: true,
+      supply: true,
+      remainingSupply: true,
+      fillRateBps: true,
+      admissionWindows: { startsAt: true, endsAt: true },
+    },
+  },
+});
+
+const tier = context.tiers.find((candidate) => candidate.eligible)!;
+const { applyPartnerMomentDynamicPricing: batch } = await itm.mutation({
+  applyPartnerMomentDynamicPricing: {
+    __args: {
+      input: {
+        momentUid,
+        mode: "APPLY", // use PREVIEW to validate without changing prices
+        idempotencyKey: crypto.randomUUID(),
+        policyVersion: context.policy.version,
+        reason: "60% fill threshold reached",
+        strategyKey: "capacity-step",
+        strategyVersion: "1.0.0",
+        updates: [
+          {
+            ticketTierUid: tier.ticketTierUid,
+            newPrice: tier.currentPrice + 500,
+            expectedPrice: tier.currentPrice,
+            expectedPricingContextVersion: tier.pricingContextVersion,
+            inventoryGuard: {
+              mode: "RANGE",
+              metric: "FILL_RATE_BPS",
+              minimum: 6000,
+              maximum: 6999,
+            },
+          },
+        ],
+      },
+    },
+    uid: true,
+    status: true,
+    failureCode: true,
+    failureMessage: true,
+    items: {
+      ticketTierUid: true,
+      status: true,
+      previousPrice: true,
+      resultingPrice: true,
+      failureCode: true,
+    },
+  },
+});
+```
+
+Reuse an idempotency key only for the identical request. `PROCESSING` can be
+polled with `getPartnerDynamicPricingBatch`; terminal statuses are `PREVIEWED`,
+`APPLIED`, `NO_CHANGES`, `REJECTED`, `CONFLICTED`, and `FAILED`. Legacy
+`editPartnerTicketTiersForMoment` price edits are rejected for tiers enrolled
+in an enabled dynamic pricing policy.
+
+Use `{ mode: 'INDEPENDENT' }` only when the strategy intentionally does not
+depend on live capacity. Range bounds are inclusive; fill rate uses integer
+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.
+
 ## Available Queries
 
+### `getPartnerBrand`
+
+Get details for the brand associated with the partner token. Takes no
+arguments — the brand is resolved from the authenticated token, and the
+response is always non-null.
+
+```typescript
+const { getPartnerBrand } = await itm.query({
+  getPartnerBrand: {
+    uid: true,
+    name: true,
+    slug: true,
+    bio: true,
+    publicUrl: true,
+    customDomain: true,
+    customDomainVerifiedAt: true,
+    spotifyUrl: true,
+    youtubeEmbedUrl: true,
+  },
+});
+```
+
+- `publicUrl` is the brand's hosted page on ITM.
+- `customDomain` and `customDomainVerifiedAt` describe the brand's white-label
+  domain, if one is configured; `customDomainVerifiedAt` is `null` until the
+  domain is verified.
+- `bio`, `spotifyUrl`, and `youtubeEmbedUrl` are `null` when unset.
+
 ### `getPartnerMomentsForBrand`
 
 Get paginated moments (events) for your brand.
@@ -124,10 +261,10 @@ Get paginated moments (events) for your brand.
 const { getPartnerMomentsForBrand } = await itm.query({
   getPartnerMomentsForBrand: {
     __args: {
-      take: 20,             // items per page (default: 50, omit to use default)
-      cursor: nextCursor,   // from previous response
-      status: 'UPCOMING',   // UPCOMING | LIVE | ENDED
-      sortOrder: 'ASC',     // ASC | DESC by start date (default: DESC)
+      take: 20, // items per page (default: 50, omit to use default)
+      cursor: nextCursor, // from previous response
+      status: "UPCOMING", // UPCOMING | LIVE | ENDED
+      sortOrder: "ASC", // ASC | DESC by start date (default: DESC)
     },
     moments: { uid: true, name: true, startDate: true },
     totalCount: true,
@@ -137,6 +274,60 @@ const { getPartnerMomentsForBrand } = await itm.query({
 });
 ```
 
+### `getPartnerDrops`
+
+Get paginated brand drops for the brand associated with your partner token.
+Use this for partner-hosted drop grids, release pages, and filtered merch or
+music drop listings.
+
+Supported filters:
+
+- `search`: case-insensitive match across drop name, subtitle, and slug.
+- `isPublic`: filter public or private drops.
+- `ctaType`: filter by `EXTERNAL_URL`, `GATED_LINK`, `MUSIC_LINK`, or `SUBSCRIBE`.
+- `cursor` and `take`: use `nextCursor` while `hasNextPage` is true.
+
+```typescript
+const { getPartnerDrops } = await itm.query({
+  getPartnerDrops: {
+    __args: {
+      take: 20,
+      cursor: nextCursor,
+      search: "release",
+      isPublic: true,
+      ctaType: "EXTERNAL_URL", // EXTERNAL_URL | GATED_LINK | MUSIC_LINK | SUBSCRIBE
+    },
+    drops: {
+      uid: true,
+      name: true,
+      slug: true,
+      isPublic: true,
+      ctaType: true,
+      ctaUrl: true,
+      captureName: true,
+      captureEmail: true,
+      coverImage: { url: true, mimeType: true },
+      coverImageMobile: { url: true, mimeType: true },
+      musicLink: {
+        title: true,
+        artistName: true,
+        releaseType: true,
+        sourceUrl: true,
+        odesliPageUrl: true,
+        thumbnailUrl: true,
+      },
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+The response is always scoped by the partner token; do not pass a brand ID.
+`coverImageMobile` and `musicLink` can be `null`, so handle those as optional in
+rendering code.
+
 ### `getPartnerMoment`
 
 Get a single moment by slug.
@@ -144,7 +335,7 @@ Get a single moment by slug.
 ```typescript
 const { getPartnerMoment } = await itm.query({
   getPartnerMoment: {
-    __args: { slug: 'my-event-slug' },
+    __args: { slug: "my-event-slug" },
     uid: true,
     name: true,
     startDate: true,
@@ -172,7 +363,7 @@ Get approved public lineup entries for a moment. Use `getPartnerMoment` first if
 ```typescript
 const { getPartnerMoment } = await itm.query({
   getPartnerMoment: {
-    __args: { slug: 'my-event-slug' },
+    __args: { slug: "my-event-slug" },
     uid: true,
     lineupDisplayLabel: true,
   },
@@ -186,7 +377,7 @@ if (momentUid) {
       __args: {
         momentUid,
         take: 50,
-        lineupType: 'DJ', // optional: LINEUP | CO_HOST | PROMOTER | DJ | SPEAKER | VENDOR
+        lineupType: "DJ", // optional: LINEUP | CO_HOST | PROMOTER | DJ | SPEAKER | VENDOR
       },
       lineups: {
         uid: true,
@@ -206,7 +397,10 @@ if (momentUid) {
     },
   });
 
-  console.log(getPartnerMoment?.lineupDisplayLabel, getPublicMomentLineups.lineups);
+  console.log(
+    getPartnerMoment?.lineupDisplayLabel,
+    getPublicMomentLineups.lineups
+  );
 }
 ```
 
@@ -221,7 +415,7 @@ Get public lineup invitation details by response token. This is useful if you bu
 ```typescript
 const { getMomentLineupByToken } = await itm.query({
   getMomentLineupByToken: {
-    __args: { token: 'lineup-response-token' },
+    __args: { token: "lineup-response-token" },
     artistName: true,
     momentName: true,
     brandName: true,
@@ -232,7 +426,7 @@ const { getMomentLineupByToken } = await itm.query({
 });
 ```
 
-### `getMomentStats`
+### `getPartnerMomentStats`
 
 Get cached partner-facing counts for a moment owned by the authenticated partner's brand.
 
@@ -242,9 +436,9 @@ Get cached partner-facing counts for a moment owned by the authenticated partner
 - `ticketRsvpRequestsCount` counts ticket RSVP requests.
 
 ```typescript
-const { getMomentStats } = await itm.query({
-  getMomentStats: {
-    __args: { momentSlug: 'my-event-slug' },
+const { getPartnerMomentStats } = await itm.query({
+  getPartnerMomentStats: {
+    __args: { momentSlug: "my-event-slug" },
     ticketsCount: true,
     waitlistCount: true,
     externalRsvpCount: true,
@@ -253,7 +447,109 @@ const { getMomentStats } = await itm.query({
 });
 ```
 
-> **Note:** `getMomentStats` returns `null` if the moment does not exist or is not owned by the authenticated partner's brand.
+> **Note:** `getPartnerMomentStats` returns `null` if the moment does not exist or is not owned by the authenticated partner's brand.
+
+### `getPartnerMomentAttendanceStats`
+
+Get a cached attendance snapshot for a moment owned by the authenticated
+partner's brand. Counts can be up to five minutes old; `generatedAt` reports
+when the snapshot was produced.
+
+Look up the moment by exactly one of:
+
+- `momentUid` — the ITM moment UID
+- `momentSlug` — the ITM moment slug
+- `externalPlatform` + `externalId` — the source-platform identifier for
+  imported events (for example `EVENTBRITE`); the two must be provided together
+
+```typescript
+const { getPartnerMomentAttendanceStats } = await itm.query({
+  getPartnerMomentAttendanceStats: {
+    __args: {
+      input: { externalPlatform: "EVENTBRITE", externalId: "1234567890" },
+    },
+    momentUid: true,
+    momentSlug: true,
+    generatedAt: true,
+    tickets: {
+      total: true,
+      checkedIn: true,
+      tiers: {
+        tierUid: true,
+        name: true,
+        label: true,
+        total: true,
+        checkedIn: true,
+      },
+    },
+    guestlist: {
+      total: true,
+      checkedIn: true,
+      unlabeled: { total: true, checkedIn: true },
+      labels: { labelUid: true, name: true, total: true, checkedIn: true },
+    },
+  },
+});
+```
+
+- `tickets` counts confirmed tickets, overall and per ticket tier.
+- `guestlist` counts guest-list entries, split into `unlabeled` and per-label
+  buckets.
+
+> **Note:** Returns `null` if no moment matches the lookup or the moment is not
+> owned by the authenticated partner's brand. The request fails with a
+> validation error when an identifier is an empty string, when
+> `externalPlatform` and `externalId` are not provided together, when more than
+> one lookup key is given, or when an external ID matches multiple moments.
+
+### `getPartnerTicketTiersForMoment`
+
+Get paginated, partner-facing ticket tiers for a moment. Use this for pricing,
+inventory, and dynamic catalog views without selecting the full public `Moment`
+payload.
+
+Provide either `momentSlug` or `momentUid`. If `isActive` is omitted, the backend
+returns active tiers only; pass `isActive: false` only when you intentionally need
+inactive tiers.
+
+```typescript
+const { getPartnerTicketTiersForMoment } = await itm.query({
+  getPartnerTicketTiersForMoment: {
+    __args: {
+      input: {
+        momentSlug: "my-event-slug",
+        take: 20,
+        search: "general",
+        isPaid: true,
+        minPrice: 1000, // cents
+        maxPrice: 5000, // cents
+      },
+    },
+    ticketTiers: {
+      uid: true,
+      name: true,
+      label: true,
+      labelColor: true,
+      price: true, // cents
+      supply: true,
+      remainingSupply: true,
+      fillRate: true, // 0-1 sold-through ratio
+      isActive: true,
+      isPrivate: true,
+      slotDate: true,
+      slotDurationHours: true,
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+Supported filters include `ticketTierUids`, `search`, `isActive`, `isPrivate`,
+`isPaid`, exact/min/max `price`, exact/min/max `supply`, exact/min/max
+`remainingSupply`, min/max `fillRate`, admission-window bounds (`startsAt`,
+`endsAt`), and slot date bounds (`slotDateStart`, `slotDateEnd`).
 
 ### `getPartnerTicketsForMoment`
 
@@ -263,8 +559,8 @@ Get paginated tickets for a moment.
 const { getPartnerTicketsForMoment } = await itm.query({
   getPartnerTicketsForMoment: {
     __args: {
-      momentSlug: 'my-event-slug',
-      checkedIn: true,  // optional: filter by check-in status
+      momentSlug: "my-event-slug",
+      checkedIn: true, // optional: filter by check-in status
       take: 50,
     },
     tickets: {
@@ -290,7 +586,7 @@ Get paginated customers (users with their tickets) for a moment.
 ```typescript
 const { getPartnerCustomersForMoment } = await itm.query({
   getPartnerCustomersForMoment: {
-    __args: { momentSlug: 'my-event-slug', take: 50 },
+    __args: { momentSlug: "my-event-slug", take: 50 },
     customers: {
       user: { uid: true, name: true, primaryEmail: true, phoneNumber: true },
       tickets: { uid: true, price: true, redeemedAt: true },
@@ -309,7 +605,7 @@ Get a moment collection by slug. Collections group related moments together (e.g
 ```typescript
 const { getPartnerMomentCollection } = await itm.query({
   getPartnerMomentCollection: {
-    __args: { slug: 'summer-series' },
+    __args: { slug: "summer-series" },
     uid: true,
     name: true,
     description: true,
@@ -350,10 +646,10 @@ You can filter moments within a collection using `queryFilters`:
 ```typescript
 const { getPartnerMomentCollection } = await itm.query({
   getPartnerMomentCollection: {
-    __args: { slug: 'summer-series' },
+    __args: { slug: "summer-series" },
     name: true,
     moments: {
-      __args: { queryFilters: ['upcoming'] },
+      __args: { queryFilters: ["upcoming"] },
       uid: true,
       name: true,
       startDate: true,
@@ -411,7 +707,7 @@ Filter by moment to get echoes scoped to a specific event:
 ```typescript
 const { getPartnerPublicEchoes } = await itm.query({
   getPartnerPublicEchoes: {
-    __args: { momentSlug: 'my-event-slug', take: 10 },
+    __args: { momentSlug: "my-event-slug", take: 10 },
     echoes: {
       uid: true,
       type: true,
@@ -445,8 +741,8 @@ const { respondToMomentLineup } = await itm.mutation({
   respondToMomentLineup: {
     __args: {
       input: {
-        token: 'lineup-response-token',
-        status: 'APPROVED', // APPROVED or REJECTED
+        token: "lineup-response-token",
+        status: "APPROVED", // APPROVED or REJECTED
       },
     },
     status: true,
@@ -470,10 +766,10 @@ Use OTP subscribe when you want the user to confirm the phone number before the
 
 ### Flow Summary
 
-| Mode | First mutation | First response | Second mutation |
-|---|---|---|---|
-| Direct | `createPartnerBrandSubscription` with `requireOtpVerification: false` or omitted | `verificationRequired: false` and `subscription` populated | None |
-| OTP | `createPartnerBrandSubscription` with `requireOtpVerification: true` | `verificationRequired: true`, `verificationToken`, `subscription: null` | `verifyPartnerBrandSubscription` |
+| Mode   | First mutation                                                                   | First response                                                          | Second mutation                  |
+| ------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------- |
+| Direct | `createPartnerBrandSubscription` with `requireOtpVerification: false` or omitted | `verificationRequired: false` and `subscription` populated              | None                             |
+| OTP    | `createPartnerBrandSubscription` with `requireOtpVerification: true`             | `verificationRequired: true`, `verificationToken`, `subscription: null` | `verifyPartnerBrandSubscription` |
 
 ### Input Behavior
 
@@ -508,27 +804,27 @@ The field is part of the generated SDK input types:
 import type {
   CreatePartnerBrandSubscriptionInput,
   PostSubscriptionMessageInput,
-} from '@itm-studio/partner-sdk';
+} from "@itm-studio/partner-sdk";
 
 const welcomeMessage: PostSubscriptionMessageInput = {
   sms: {
-    body: 'Welcome to Acme. Reply STOP to opt out.',
-    mediaUrls: ['https://cdn.example.com/welcome-banner.png'],
+    body: "Welcome to Acme. Reply STOP to opt out.",
+    mediaUrls: ["https://cdn.example.com/welcome-banner.png"],
   },
   email: {
-    subject: 'Welcome to Acme',
-    body: 'Thanks for subscribing. Your first update is on the way.',
+    subject: "Welcome to Acme",
+    body: "Thanks for subscribing. Your first update is on the way.",
   },
   push: {
-    title: 'Welcome to Acme',
-    body: 'Tap to see what is dropping this week.',
+    title: "Welcome to Acme",
+    body: "Tap to see what is dropping this week.",
   },
 };
 
 const input: CreatePartnerBrandSubscriptionInput = {
-  phoneNumber: '+14155550111',
-  fullName: 'Jane Doe',
-  email: 'jane@example.com',
+  phoneNumber: "+14155550111",
+  fullName: "Jane Doe",
+  email: "jane@example.com",
   postSubscriptionMessage: welcomeMessage,
 };
 ```
@@ -538,21 +834,21 @@ await itm.mutation({
   createPartnerBrandSubscription: {
     __args: {
       input: {
-        phoneNumber: '+14155550111',
-        fullName: 'Jane Doe',
-        email: 'jane@example.com',
+        phoneNumber: "+14155550111",
+        fullName: "Jane Doe",
+        email: "jane@example.com",
         postSubscriptionMessage: {
           sms: {
-            body: 'Welcome to Acme — your first drop ships Friday. Reply STOP to opt out.',
-            mediaUrls: ['https://cdn.example.com/welcome-banner.png'],
+            body: "Welcome to Acme — your first drop ships Friday. Reply STOP to opt out.",
+            mediaUrls: ["https://cdn.example.com/welcome-banner.png"],
           },
           email: {
-            subject: 'Welcome to Acme',
-            body: 'Hi Jane,\n\nThanks for subscribing — here is what to expect next...',
+            subject: "Welcome to Acme",
+            body: "Hi Jane,\n\nThanks for subscribing — here is what to expect next...",
           },
           push: {
-            title: 'Welcome to Acme',
-            body: 'Tap to see what is dropping this week.',
+            title: "Welcome to Acme",
+            body: "Tap to see what is dropping this week.",
           },
         },
       },
@@ -565,20 +861,20 @@ await itm.mutation({
 
 **Direct vs OTP timing:**
 
-| Mode | Where to pass `postSubscriptionMessage` | When delivery starts |
-|---|---|---|
-| Direct subscribe | Initial `createPartnerBrandSubscription` call | After the subscription is created or reactivated |
-| OTP subscribe | Initial `createPartnerBrandSubscription` call with `requireOtpVerification: true` | After `verifyPartnerBrandSubscription` succeeds |
+| Mode             | Where to pass `postSubscriptionMessage`                                           | When delivery starts                             |
+| ---------------- | --------------------------------------------------------------------------------- | ------------------------------------------------ |
+| Direct subscribe | Initial `createPartnerBrandSubscription` call                                     | After the subscription is created or reactivated |
+| OTP subscribe    | Initial `createPartnerBrandSubscription` call with `requireOtpVerification: true` | After `verifyPartnerBrandSubscription` succeeds  |
 
 Do not pass `postSubscriptionMessage` to `verifyPartnerBrandSubscription`; that mutation only accepts `verificationToken` and `code`.
 
 **Channel inputs:**
 
-| Channel | Required | Optional | Notes |
-|---|---|---|---|
-| `sms` | `body` | `mediaUrls` (string array of image URLs for MMS) | Delivered to `phoneNumber`. |
-| `email` | `subject`, `body` | — | `body` is plain text or markdown, rendered via React Email. Skipped if the user has no primary email or the brand has no configured email alias. |
-| `push` | `title`, `body` | — | Skipped if the user has no push tokens or has opted out of brand messages. |
+| Channel | Required          | Optional                                         | Notes                                                                                                                                            |
+| ------- | ----------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `sms`   | `body`            | `mediaUrls` (string array of image URLs for MMS) | Delivered to `phoneNumber`.                                                                                                                      |
+| `email` | `subject`, `body` | —                                                | `body` is plain text or markdown, rendered via React Email. Skipped if the user has no primary email or the brand has no configured email alias. |
+| `push`  | `title`, `body`   | —                                                | Skipped if the user has no push tokens or has opted out of brand messages.                                                                       |
 
 **Delivery semantics:**
 
@@ -602,10 +898,10 @@ await itm.mutation({
   createPartnerBrandSubscription: {
     __args: {
       input: {
-        phoneNumber: '+14155550111',
+        phoneNumber: "+14155550111",
         postSubscriptionMessage: {
           sms: {
-            body: 'You are subscribed to Acme updates. Reply STOP to opt out.',
+            body: "You are subscribed to Acme updates. Reply STOP to opt out.",
           },
         },
       },
@@ -623,16 +919,16 @@ const { createPartnerBrandSubscription } = await itm.mutation({
   createPartnerBrandSubscription: {
     __args: {
       input: {
-        phoneNumber: '+14155550112',
+        phoneNumber: "+14155550112",
         requireOtpVerification: true,
-        email: 'jane@example.com',
+        email: "jane@example.com",
         postSubscriptionMessage: {
           sms: {
-            body: 'Thanks for joining Acme. Reply STOP to opt out.',
+            body: "Thanks for joining Acme. Reply STOP to opt out.",
           },
           email: {
-            subject: 'You are subscribed',
-            body: 'Your subscription is confirmed. We will send updates here.',
+            subject: "You are subscribed",
+            body: "Your subscription is confirmed. We will send updates here.",
           },
         },
       },
@@ -648,7 +944,7 @@ await itm.mutation({
     __args: {
       input: {
         verificationToken: createPartnerBrandSubscription.verificationToken!,
-        code: '123456',
+        code: "123456",
       },
     },
     uid: true,
@@ -671,17 +967,17 @@ const { createPartnerBrandSubscription } = await itm.mutation({
   createPartnerBrandSubscription: {
     __args: {
       input: {
-        phoneNumber: '+14155550111',
-        fullName: 'Jane Doe',
-        email: 'jane@example.com',
-        listNames: ['VIP', 'Newsletter'],
+        phoneNumber: "+14155550111",
+        fullName: "Jane Doe",
+        email: "jane@example.com",
+        listNames: ["VIP", "Newsletter"],
         compliance: {
-          pageUrl: 'https://example.com/signup',
-          submissionMethod: 'partner_sdk',
+          pageUrl: "https://example.com/signup",
+          submissionMethod: "partner_sdk",
         },
         postSubscriptionMessage: {
           sms: {
-            body: 'Welcome to Acme updates. Reply STOP to opt out.',
+            body: "Welcome to Acme updates. Reply STOP to opt out.",
           },
         },
       },
@@ -718,12 +1014,12 @@ const { createPartnerBrandSubscription } = await itm.mutation({
   createPartnerBrandSubscription: {
     __args: {
       input: {
-        phoneNumber: '+14155550112',
+        phoneNumber: "+14155550112",
         requireOtpVerification: true,
-        fullName: 'Otp User',
+        fullName: "Otp User",
         compliance: {
-          pageUrl: 'https://example.com/otp-signup',
-          submissionMethod: 'partner_sdk',
+          pageUrl: "https://example.com/otp-signup",
+          submissionMethod: "partner_sdk",
         },
       },
     },
@@ -733,18 +1029,17 @@ const { createPartnerBrandSubscription } = await itm.mutation({
 });
 
 if (!createPartnerBrandSubscription.verificationToken) {
-  throw new Error('Expected OTP verification to be required');
+  throw new Error("Expected OTP verification to be required");
 }
 
 // Collect the SMS code from the user in your UI or API flow.
-const code = '123456';
+const code = "123456";
 
 const { verifyPartnerBrandSubscription } = await itm.mutation({
   verifyPartnerBrandSubscription: {
     __args: {
       input: {
-        verificationToken:
-          createPartnerBrandSubscription.verificationToken,
+        verificationToken: createPartnerBrandSubscription.verificationToken,
         code,
       },
     },
@@ -770,17 +1065,17 @@ This is the recommended mode when:
 This is the full two-step flow most integrators will want to implement from a server route or server action.
 
 ```typescript
-import { createITMPartnerClient } from '@itm-studio/partner-sdk';
+import { createITMPartnerClient } from "@itm-studio/partner-sdk";
 
 function createRequestScopedITM(request: Request) {
   return createITMPartnerClient({
     token: process.env.ITM_PARTNER_TOKEN!,
     headers: () => ({
-      ...(request.headers.get('x-forwarded-for')
-        ? { 'x-forwarded-for': request.headers.get('x-forwarded-for')! }
+      ...(request.headers.get("x-forwarded-for")
+        ? { "x-forwarded-for": request.headers.get("x-forwarded-for")! }
         : {}),
-      ...(request.headers.get('user-agent')
-        ? { 'user-agent': request.headers.get('user-agent')! }
+      ...(request.headers.get("user-agent")
+        ? { "user-agent": request.headers.get("user-agent")! }
         : {}),
     }),
   });
@@ -793,24 +1088,24 @@ export async function startOtpSubscription(request: Request) {
     createPartnerBrandSubscription: {
       __args: {
         input: {
-          phoneNumber: '+14155550112',
+          phoneNumber: "+14155550112",
           requireOtpVerification: true,
-          fullName: 'Otp User',
-          email: 'otp@example.com',
-          listNames: ['Members', 'SMS'],
+          fullName: "Otp User",
+          email: "otp@example.com",
+          listNames: ["Members", "SMS"],
           compliance: {
-            pageUrl: 'https://example.com/join',
-            submissionMethod: 'partner_sdk',
+            pageUrl: "https://example.com/join",
+            submissionMethod: "partner_sdk",
             submittedAt: new Date().toISOString(),
-            timezone: 'America/New_York',
+            timezone: "America/New_York",
           },
           postSubscriptionMessage: {
             sms: {
-              body: 'You are subscribed. Reply STOP to opt out.',
+              body: "You are subscribed. Reply STOP to opt out.",
             },
             email: {
-              subject: 'Welcome',
-              body: 'Your subscription is confirmed.',
+              subject: "Welcome",
+              body: "Your subscription is confirmed.",
             },
           },
         },
@@ -825,13 +1120,13 @@ export async function startOtpSubscription(request: Request) {
 
   if (!createPartnerBrandSubscription.verificationRequired) {
     return {
-      status: 'subscribed',
+      status: "subscribed",
       subscriptionUid: createPartnerBrandSubscription.subscription?.uid ?? null,
     };
   }
 
   return {
-    status: 'otp_required',
+    status: "otp_required",
     verificationToken: createPartnerBrandSubscription.verificationToken,
   };
 }
@@ -839,7 +1134,7 @@ export async function startOtpSubscription(request: Request) {
 export async function finishOtpSubscription(
   request: Request,
   verificationToken: string,
-  code: string,
+  code: string
 ) {
   const itm = createRequestScopedITM(request);
 
@@ -880,7 +1175,7 @@ Get a presigned S3 URL to upload a file directly.
 ```typescript
 const { getPartnerUploadUrl } = await itm.mutation({
   getPartnerUploadUrl: {
-    __args: { filename: 'event-cover', fileExtension: 'jpg' },
+    __args: { filename: "event-cover", fileExtension: "jpg" },
     url: true,
     filename: true,
   },
@@ -888,9 +1183,9 @@ const { getPartnerUploadUrl } = await itm.mutation({
 
 // Upload the file to S3 using the presigned URL
 await fetch(getPartnerUploadUrl.url, {
-  method: 'PUT',
+  method: "PUT",
   body: fileBuffer, // Buffer, Blob, or ReadableStream
-  headers: { 'Content-Type': 'image/jpeg' },
+  headers: { "Content-Type": "image/jpeg" },
 });
 ```
 
@@ -902,7 +1197,7 @@ After uploading, register the asset so it's linked to your brand.
 const { createPartnerMediaAsset } = await itm.mutation({
   createPartnerMediaAsset: {
     __args: {
-      mimetype: 'image/jpeg',
+      mimetype: "image/jpeg",
       filename: getPartnerUploadUrl.filename, // from Step 1
       dimensions: { width: 1920, height: 1080 },
     },
@@ -924,37 +1219,38 @@ const { createPartnerMoment } = await itm.mutation({
   createPartnerMoment: {
     __args: {
       input: {
-        name: 'Summer Rooftop Party',
-        description: 'A rooftop party in NYC',
-        blurb: 'Join us on the roof!',
-        startDate: '2026-07-15T20:00:00.000Z',
-        endDate: '2026-07-16T02:00:00.000Z',
-        timezone: 'America/New_York',
-        type: 'IRL',
+        name: "Summer Rooftop Party",
+        description: "A rooftop party in NYC",
+        blurb: "Join us on the roof!",
+        startDate: "2026-07-15T20:00:00.000Z",
+        endDate: "2026-07-16T02:00:00.000Z",
+        timezone: "America/New_York",
+        type: "IRL",
+        capacity: 250,
         coverImageUid: createPartnerMediaAsset.uid, // from upload flow
         venue: {
-          name: 'Rooftop Bar',
-          city: 'New York',
-          country: 'US',
-          address: '123 Main St',
+          name: "Rooftop Bar",
+          city: "New York",
+          country: "US",
+          address: "123 Main St",
         },
-        category: 'PARTY',
-        subcategory: 'ROOFTOP_PARTY',
+        category: "PARTY",
+        subcategory: "ROOFTOP_PARTY",
         ticketTiers: [
           {
-            name: 'General Admission',
-            price: 2500,          // $25.00 in cents
+            name: "General Admission",
+            price: 2500, // $25.00 in cents
             supply: 200,
             maxPerUser: 4,
-            currencyCode: 'USD',
+            currencyCode: "USD",
           },
           {
-            name: 'VIP',
-            price: 7500,          // $75.00 in cents
+            name: "VIP",
+            price: 7500, // $75.00 in cents
             supply: 50,
             maxPerUser: 2,
-            currencyCode: 'USD',
-            description: 'Includes open bar',
+            currencyCode: "USD",
+            description: "Includes open bar",
           },
         ],
       },
@@ -965,6 +1261,7 @@ const { createPartnerMoment } = await itm.mutation({
     startDate: true,
     endDate: true,
     status: true,
+    capacity: true,
     coverImage: { url: true },
     venue: { name: true, city: true },
     ticketTiers: {
@@ -978,19 +1275,93 @@ const { createPartnerMoment } = await itm.mutation({
 });
 ```
 
-**Required fields:** `name`, `description`, `blurb`, `startDate`, `endDate`, `timezone`, `type`
+**Required fields:** `name`, `description`, `startDate`, `endDate`, `timezone`, `type`
 
 **Moment types:**
+
 - `IRL` — in-person event (requires `venue`)
-- `DIGITAL` — online event (no venue needed)
+- `DIGITAL` — online event (no venue needed; accepts `onlineConfig`)
+- `HYBRID` — venue plus online access. When creating ticket tiers for a hybrid moment, set each tier's `attendanceMode` to `IN_PERSON` or `ONLINE`.
+
+For digital or hybrid moments, pass `onlineConfig` when you want ITM to store the meeting details:
+
+```typescript
+await itm.mutation({
+  createPartnerMoment: {
+    __args: {
+      input: {
+        name: "Hybrid Show",
+        description: "Attend in person or online",
+        startDate: "2026-07-15T20:00:00.000Z",
+        endDate: "2026-07-15T23:00:00.000Z",
+        timezone: "America/New_York",
+        type: "HYBRID",
+        onlineConfig: {
+          provider: "ZOOM", // GOOGLE_MEET | MS_TEAMS | OTHER | ZOOM
+          meetingUrl: "https://zoom.us/j/123456789",
+          meetingPasscode: "club",
+        },
+        venue: { name: "Main Room", city: "New York", country: "US" },
+        ticketTiers: [
+          {
+            name: "Online Admission",
+            price: 1500,
+            supply: 300,
+            maxPerUser: 4,
+            currencyCode: "USD",
+            attendanceMode: "ONLINE",
+          },
+        ],
+      },
+    },
+    uid: true,
+    type: true,
+    ticketTiers: { uid: true, attendanceMode: true },
+  },
+});
+```
 
 **Ticket tier pricing:** `price` is in **cents** (e.g. `2500` = $25.00 for USD). Use `0` for free tiers. See [Money Amounts](#money-amounts) for display formatting, including zero-decimal currencies.
 
+### `editPartnerTicketTiersForMoment`
+
+Bulk edit partner-owned ticket tiers for a moment. Provide either `momentSlug` or
+`momentUid`, then target specific tiers by `ticketTierUid`.
+
+This endpoint intentionally supports only `price` and `supply` updates. Use
+`getPartnerTicketTiersForMoment` first if you need to discover tier UIDs.
+
+```typescript
+const { editPartnerTicketTiersForMoment } = await itm.mutation({
+  editPartnerTicketTiersForMoment: {
+    __args: {
+      input: {
+        momentSlug: "my-event-slug",
+        updates: [
+          {
+            ticketTierUid: "tier-uid",
+            price: 3000, // cents
+            supply: 120,
+          },
+        ],
+      },
+    },
+    uid: true,
+    name: true,
+    price: true,
+    supply: true,
+    remainingSupply: true,
+    fillRate: true,
+    isActive: true,
+  },
+});
+```
+
 ### Complete Upload + Create Moment Flow
 
 ```typescript
-import { createITMPartnerClient } from '@itm-studio/partner-sdk';
-import { readFile } from 'fs/promises';
+import { createITMPartnerClient } from "@itm-studio/partner-sdk";
+import { readFile } from "fs/promises";
 
 const itm = createITMPartnerClient({
   token: process.env.ITM_PARTNER_TOKEN!,
@@ -999,25 +1370,25 @@ const itm = createITMPartnerClient({
 // 1. Get presigned upload URL
 const { getPartnerUploadUrl } = await itm.mutation({
   getPartnerUploadUrl: {
-    __args: { filename: 'event-cover', fileExtension: 'jpg' },
+    __args: { filename: "event-cover", fileExtension: "jpg" },
     url: true,
     filename: true,
   },
 });
 
 // 2. Upload file to S3
-const file = await readFile('./event-cover.jpg');
+const file = await readFile("./event-cover.jpg");
 await fetch(getPartnerUploadUrl.url, {
-  method: 'PUT',
+  method: "PUT",
   body: file,
-  headers: { 'Content-Type': 'image/jpeg' },
+  headers: { "Content-Type": "image/jpeg" },
 });
 
 // 3. Register the uploaded asset
 const { createPartnerMediaAsset } = await itm.mutation({
   createPartnerMediaAsset: {
     __args: {
-      mimetype: 'image/jpeg',
+      mimetype: "image/jpeg",
       filename: getPartnerUploadUrl.filename,
       dimensions: { width: 1920, height: 1080 },
     },
@@ -1030,26 +1401,26 @@ const { createPartnerMoment } = await itm.mutation({
   createPartnerMoment: {
     __args: {
       input: {
-        name: 'My Event',
-        description: 'An amazing event',
-        blurb: 'Come join us!',
-        startDate: '2026-07-15T20:00:00.000Z',
-        endDate: '2026-07-16T02:00:00.000Z',
-        timezone: 'America/New_York',
-        type: 'IRL',
+        name: "My Event",
+        description: "An amazing event",
+        blurb: "Come join us!",
+        startDate: "2026-07-15T20:00:00.000Z",
+        endDate: "2026-07-16T02:00:00.000Z",
+        timezone: "America/New_York",
+        type: "IRL",
         coverImageUid: createPartnerMediaAsset.uid,
         venue: {
-          name: 'The Venue',
-          city: 'New York',
-          country: 'US',
+          name: "The Venue",
+          city: "New York",
+          country: "US",
         },
         ticketTiers: [
           {
-            name: 'General Admission',
+            name: "General Admission",
             price: 2500,
             supply: 100,
             maxPerUser: 4,
-            currencyCode: 'USD',
+            currencyCode: "USD",
           },
         ],
       },
@@ -1061,7 +1432,9 @@ const { createPartnerMoment } = await itm.mutation({
   },
 });
 
-console.log(`Created: ${createPartnerMoment.slug} (${createPartnerMoment.status})`);
+console.log(
+  `Created: ${createPartnerMoment.slug} (${createPartnerMoment.status})`
+);
 ```
 
 ## Pagination
@@ -1074,7 +1447,7 @@ let cursor: string | null = null;
 do {
   const { getPartnerTicketsForMoment } = await itm.query({
     getPartnerTicketsForMoment: {
-      __args: { momentSlug: 'my-event', cursor, take: 50 },
+      __args: { momentSlug: "my-event", cursor, take: 50 },
       tickets: { uid: true, user: { name: true } },
       hasNextPage: true,
       nextCursor: true,
@@ -1097,7 +1470,7 @@ For staging or local development:
 ```typescript
 const itm = createITMPartnerClient({
   token: process.env.ITM_PARTNER_TOKEN!,
-  baseUrl: 'https://staging-api.itm.studio/graphql',
+  baseUrl: "https://staging-api.itm.studio/graphql",
 });
 ```
 
@@ -1157,12 +1530,12 @@ npm run schema:publish  # Publish schema to registry
 
 ## CI/CD
 
-| Job | Trigger | What it does |
-|---|---|---|
-| `build-and-test` | Every push & PR | Install, generate, lint, test, build |
-| `schema-check` | PRs only | Validates schema changes won't break partners |
-| `schema-publish` | Push to main | Publishes schema to Hive registry |
-| `publish` | Push to main | Auto-bumps patch version and publishes to NPM |
+| Job              | Trigger         | What it does                                  |
+| ---------------- | --------------- | --------------------------------------------- |
+| `build-and-test` | Every push & PR | Install, generate, lint, test, build          |
+| `schema-check`   | PRs only        | Validates schema changes won't break partners |
+| `schema-publish` | Push to main    | Publishes schema to Hive registry             |
+| `publish`        | Push to main    | Auto-bumps patch version and publishes to NPM |
 
 ## Adding New Partner Endpoints