@itm-studio/partner-sdk 0.2.0 → 0.2.2

package/README.md

@@ -64,6 +64,31 @@ Get your partner API token from the ITM backstage dashboard: **Settings > Partne
 
 The token is sent as the `x-partner-api-key` header on every request. Your brand is determined automatically from the token — no need to pass brand IDs.
 
+Keep the partner token on your server. Do not expose it from browser code or client-side mobile code.
+
+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';
+
+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');
+
+      return {
+        ...(forwardedFor ? { 'x-forwarded-for': forwardedFor } : {}),
+        ...(userAgent ? { 'user-agent': userAgent } : {}),
+      };
+    },
+  });
+}
+```
+
+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.
+
 ## Available Queries
 
 ### `getPartnerMomentsForBrand`
@@ -114,6 +139,29 @@ const { getPartnerMoment } = await itm.query({
 });
 ```
 
+### `getMomentStats`
+
+Get cached partner-facing counts for a moment owned by the authenticated partner's brand.
+
+- `ticketsCount` counts confirmed tickets only.
+- `waitlistCount` counts active waitlist entries.
+- `externalRsvpCount` counts external RSVPs.
+- `ticketRsvpRequestsCount` counts ticket RSVP requests.
+
+```typescript
+const { getMomentStats } = await itm.query({
+  getMomentStats: {
+    __args: { momentSlug: 'my-event-slug' },
+    ticketsCount: true,
+    waitlistCount: true,
+    externalRsvpCount: true,
+    ticketRsvpRequestsCount: true,
+  },
+});
+```
+
+> **Note:** `getMomentStats` returns `null` if the moment does not exist or is not owned by the authenticated partner's brand.
+
 ### `getPartnerTicketsForMoment`
 
 Get paginated tickets for a moment.
@@ -295,6 +343,241 @@ const { getPartnerPublicEchoes } = await itm.query({
 
 The SDK supports write operations via `client.mutation()`. All mutations use the same authentication — your brand is determined from the token.
 
+## Partner Brand Subscription Guide
+
+The partner brand subscription API supports two integration modes:
+
+- Direct subscribe: create the subscription immediately in one mutation.
+- OTP subscribe: send an SMS code first, then confirm with a second mutation.
+
+Use direct subscribe when your product already has the right consent flow and you do not need to prove possession of the phone number in real time.
+
+Use OTP subscribe when you want the user to confirm the phone number before the brand subscription is created.
+
+### 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` |
+
+### Input Behavior
+
+- `phoneNumber`: send an E.164 phone number such as `+14155551234`.
+- `fullName`: optional, but if you send it, include both first and last name.
+- `email`: optional and attached to the subscribed user if provided.
+- `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.
+
+### OTP Flow Step By Step
+
+1. Call `createPartnerBrandSubscription` with `requireOtpVerification: true`.
+2. Store the returned `verificationToken` in the user session or another short-lived server-side state container associated with the current signup attempt.
+3. Collect the SMS code from the user.
+4. Call `verifyPartnerBrandSubscription` with that `verificationToken` and `code`.
+
+`verificationToken` is brand-scoped. A token created under one partner token cannot be verified by another brand's partner token.
+
+If the verification token is invalid or expired, verification fails and the subscription is not created.
+
+### `createPartnerBrandSubscription`
+
+Subscribe a phone number to the authenticated partner brand.
+
+- Omit `requireOtpVerification` or set it to `false` to create the subscription immediately.
+- Set `requireOtpVerification: true` to start the OTP flow. The backend sends the code to the provided phone number and returns a `verificationToken`.
+- If you pass `fullName`, include both first and last name.
+
+```typescript
+const { createPartnerBrandSubscription } = await itm.mutation({
+  createPartnerBrandSubscription: {
+    __args: {
+      input: {
+        phoneNumber: '+14155550111',
+        fullName: 'Jane Doe',
+        email: 'jane@example.com',
+        listNames: ['VIP', 'Newsletter'],
+        compliance: {
+          pageUrl: 'https://example.com/signup',
+          submissionMethod: 'partner_sdk',
+        },
+      },
+    },
+    verificationRequired: true,
+    verificationToken: true,
+    subscription: {
+      uid: true,
+      isActive: true,
+      subscribedAt: true,
+    },
+  },
+});
+
+if (!createPartnerBrandSubscription.verificationRequired) {
+  console.log(createPartnerBrandSubscription.subscription?.uid);
+}
+```
+
+When `verificationRequired` is `false`, `subscription` is populated and `verificationToken` is `null`.
+
+This is the recommended mode when:
+
+- You are subscribing from an already-authenticated server flow.
+- You already have consent and do not need phone possession verification.
+- You want a single network round trip.
+
+### `verifyPartnerBrandSubscription`
+
+Complete a subscription created with `requireOtpVerification: true`.
+
+```typescript
+const { createPartnerBrandSubscription } = await itm.mutation({
+  createPartnerBrandSubscription: {
+    __args: {
+      input: {
+        phoneNumber: '+14155550112',
+        requireOtpVerification: true,
+        fullName: 'Otp User',
+        compliance: {
+          pageUrl: 'https://example.com/otp-signup',
+          submissionMethod: 'partner_sdk',
+        },
+      },
+    },
+    verificationRequired: true,
+    verificationToken: true,
+  },
+});
+
+if (!createPartnerBrandSubscription.verificationToken) {
+  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 { verifyPartnerBrandSubscription } = await itm.mutation({
+  verifyPartnerBrandSubscription: {
+    __args: {
+      input: {
+        verificationToken:
+          createPartnerBrandSubscription.verificationToken,
+        code,
+      },
+    },
+    uid: true,
+    isActive: true,
+    subscribedAt: true,
+  },
+});
+
+console.log(verifyPartnerBrandSubscription.uid);
+```
+
+When OTP is required, `createPartnerBrandSubscription` returns `verificationRequired: true`, `subscription: null`, and a non-null `verificationToken`. Pass that token into `verifyPartnerBrandSubscription` together with the one-time code sent to the phone number.
+
+This is the recommended mode when:
+
+- The subscription starts from a public signup form.
+- You want to prove the user controls the submitted phone number.
+- Your compliance flow requires explicit OTP confirmation before the subscription is created.
+
+### Full OTP Example
+
+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';
+
+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('user-agent')
+        ? { 'user-agent': request.headers.get('user-agent')! }
+        : {}),
+    }),
+  });
+}
+
+export async function startOtpSubscription(request: Request) {
+  const itm = createRequestScopedITM(request);
+
+  const { createPartnerBrandSubscription } = await itm.mutation({
+    createPartnerBrandSubscription: {
+      __args: {
+        input: {
+          phoneNumber: '+14155550112',
+          requireOtpVerification: true,
+          fullName: 'Otp User',
+          email: 'otp@example.com',
+          listNames: ['Members', 'SMS'],
+          compliance: {
+            pageUrl: 'https://example.com/join',
+            submissionMethod: 'partner_sdk',
+            submittedAt: new Date().toISOString(),
+            timezone: 'America/New_York',
+          },
+        },
+      },
+      verificationRequired: true,
+      verificationToken: true,
+      subscription: {
+        uid: true,
+      },
+    },
+  });
+
+  if (!createPartnerBrandSubscription.verificationRequired) {
+    return {
+      status: 'subscribed',
+      subscriptionUid: createPartnerBrandSubscription.subscription?.uid ?? null,
+    };
+  }
+
+  return {
+    status: 'otp_required',
+    verificationToken: createPartnerBrandSubscription.verificationToken,
+  };
+}
+
+export async function finishOtpSubscription(
+  request: Request,
+  verificationToken: string,
+  code: string,
+) {
+  const itm = createRequestScopedITM(request);
+
+  const { verifyPartnerBrandSubscription } = await itm.mutation({
+    verifyPartnerBrandSubscription: {
+      __args: {
+        input: {
+          verificationToken,
+          code,
+        },
+      },
+      uid: true,
+      isActive: true,
+      subscribedAt: true,
+    },
+  });
+
+  return verifyPartnerBrandSubscription;
+}
+```
+
+### Common Integration Notes
+
+- Create the ITM client inside the incoming request when you need compliance backfill from headers.
+- Persist the OTP `verificationToken` only for the duration of the signup flow. Treat it as short-lived state, not a durable identifier.
+- Do not attempt to verify an OTP token with a different partner token than the one that created it.
+- If you are building a browser form, post to your own backend first, then have your backend call the ITM Partner SDK. Do not call the SDK directly from the browser.
+- If you need to associate the user with CRM-style segments on subscribe, send `listNames` during the initial create call. Those lists are created on demand.
+
 ### Media Upload Flow
 
 Uploading media (e.g. cover images) is a two-step process:

package/dist/index.d.mts

@@ -162,6 +162,13 @@ interface PartnerCustomer {
     tickets: Ticket[];
     __typename: 'PartnerCustomer';
 }
+interface PartnerMomentStats {
+    ticketsCount: Scalars['Int'];
+    waitlistCount: Scalars['Int'];
+    externalRsvpCount: Scalars['Int'];
+    ticketRsvpRequestsCount: Scalars['Int'];
+    __typename: 'PartnerMomentStats';
+}
 interface MomentCollectionLink {
     uid: Scalars['ID'];
     url: Scalars['String'];
@@ -260,11 +267,24 @@ interface GetBrandEchoesForUserResponse {
     nextCursor: (Scalars['String'] | null);
     __typename: 'GetBrandEchoesForUserResponse';
 }
+interface BrandSubscription {
+    uid: Scalars['ID'];
+    isActive: Scalars['Boolean'];
+    subscribedAt: Scalars['DateTime'];
+    createdAt: Scalars['DateTime'];
+    updatedAt: Scalars['DateTime'];
+    __typename: 'BrandSubscription';
+}
 interface Query {
     /** Get paginated moments for the brand associated with the partner token. */
     getPartnerMomentsForBrand: GetPublicMomentsResponse;
     /** Get a single moment by slug. */
     getPartnerMoment: (Moment | null);
+    /**
+     * Get cached partner-facing counts for a moment.
+     * Only returns stats for moments owned by the authenticated partner's brand.
+     */
+    getPartnerMomentStats: (PartnerMomentStats | null);
     /** Get paginated tickets for a moment. */
     getPartnerTicketsForMoment: GetTicketsResponse;
     /**
@@ -315,6 +335,12 @@ interface MediaAsset {
     updatedAt: Scalars['DateTime'];
     __typename: 'MediaAsset';
 }
+interface CreatePartnerBrandSubscriptionResponse {
+    subscription: (BrandSubscription | null);
+    verificationRequired: Scalars['Boolean'];
+    verificationToken: (Scalars['String'] | null);
+    __typename: 'CreatePartnerBrandSubscriptionResponse';
+}
 interface Mutation {
     /**
      * Get a presigned S3 URL for direct file upload.
@@ -326,11 +352,18 @@ interface Mutation {
      * Call after uploading to S3 via the presigned URL from getPartnerUploadUrl.
      */
     createPartnerMediaAsset: MediaAsset;
+    /**
+     * Subscribe a user to the authenticated partner brand.
+     * Set requireOtpVerification to true to start a two-step OTP flow.
+     */
+    createPartnerBrandSubscription: CreatePartnerBrandSubscriptionResponse;
     /**
      * Create a moment with optional venue and ticket tiers in one atomic operation.
      * When type is IRL, the venue field is required.
      */
     createPartnerMoment: Moment;
+    /** Complete a partner brand subscription that was created with requireOtpVerification=true. */
+    verifyPartnerBrandSubscription: BrandSubscription;
     __typename: 'Mutation';
 }
 interface CurrencyGenqlSelection {
@@ -484,6 +517,14 @@ interface PartnerCustomerGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface PartnerMomentStatsGenqlSelection {
+    ticketsCount?: boolean | number;
+    waitlistCount?: boolean | number;
+    externalRsvpCount?: boolean | number;
+    ticketRsvpRequestsCount?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface MomentCollectionLinkGenqlSelection {
     uid?: boolean | number;
     url?: boolean | number;
@@ -595,6 +636,15 @@ interface GetBrandEchoesForUserResponseGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface BrandSubscriptionGenqlSelection {
+    uid?: boolean | number;
+    isActive?: boolean | number;
+    subscribedAt?: boolean | number;
+    createdAt?: boolean | number;
+    updatedAt?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface QueryGenqlSelection {
     /** Get paginated moments for the brand associated with the partner token. */
     getPartnerMomentsForBrand?: (GetPublicMomentsResponseGenqlSelection & {
@@ -613,6 +663,15 @@ interface QueryGenqlSelection {
             slug: Scalars['String'];
         };
     });
+    /**
+     * Get cached partner-facing counts for a moment.
+     * Only returns stats for moments owned by the authenticated partner's brand.
+     */
+    getPartnerMomentStats?: (PartnerMomentStatsGenqlSelection & {
+        __args: {
+            momentSlug: Scalars['String'];
+        };
+    });
     /** Get paginated tickets for a moment. */
     getPartnerTicketsForMoment?: (GetTicketsResponseGenqlSelection & {
         __args: {
@@ -713,6 +772,44 @@ interface CreatePartnerMomentInput {
     /** Ticket tiers to create along with the moment. */
     ticketTiers?: (CreatePartnerTicketTierInput[] | null);
 }
+interface SubscriptionComplianceInput {
+    browserName?: (Scalars['String'] | null);
+    browserVersion?: (Scalars['String'] | null);
+    deviceType?: (Scalars['String'] | null);
+    geoAccuracy?: (Scalars['Float'] | null);
+    geoCity?: (Scalars['String'] | null);
+    geoCountry?: (Scalars['String'] | null);
+    geoLatitude?: (Scalars['Float'] | null);
+    geoLongitude?: (Scalars['Float'] | null);
+    geoRegion?: (Scalars['String'] | null);
+    ipAddress?: (Scalars['String'] | null);
+    language?: (Scalars['String'] | null);
+    osName?: (Scalars['String'] | null);
+    osVersion?: (Scalars['String'] | null);
+    pageUrl?: (Scalars['String'] | null);
+    referrerUrl?: (Scalars['String'] | null);
+    screenHeight?: (Scalars['Int'] | null);
+    screenWidth?: (Scalars['Int'] | null);
+    submissionMethod?: (Scalars['String'] | null);
+    submittedAt?: (Scalars['DateTime'] | null);
+    timezone?: (Scalars['String'] | null);
+    userAgent?: (Scalars['String'] | null);
+}
+interface CreatePartnerBrandSubscriptionInput {
+    compliance?: (SubscriptionComplianceInput | null);
+    email?: (Scalars['String'] | null);
+    /** Optional full name. If provided, include first and last name. */
+    fullName?: (Scalars['String'] | null);
+    /** Optional brand list names to attach the subscribed user to. Missing lists are created automatically. */
+    listNames?: (Scalars['String'][] | null);
+    /** E.164 phone number (for example +14155551234) */
+    phoneNumber: Scalars['String'];
+    requireOtpVerification?: (Scalars['Boolean'] | null);
+}
+interface VerifyPartnerBrandSubscriptionInput {
+    code: Scalars['String'];
+    verificationToken: Scalars['String'];
+}
 /**
  * A presigned S3 upload URL and the generated filename.
  * Returned by getPartnerUploadUrl.
@@ -745,6 +842,13 @@ interface MediaAssetGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+interface CreatePartnerBrandSubscriptionResponseGenqlSelection {
+    subscription?: BrandSubscriptionGenqlSelection;
+    verificationRequired?: boolean | number;
+    verificationToken?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface MutationGenqlSelection {
     /**
      * Get a presigned S3 URL for direct file upload.
@@ -767,6 +871,15 @@ interface MutationGenqlSelection {
             dimensions: DimensionsInput;
         };
     });
+    /**
+     * Subscribe a user to the authenticated partner brand.
+     * Set requireOtpVerification to true to start a two-step OTP flow.
+     */
+    createPartnerBrandSubscription?: (CreatePartnerBrandSubscriptionResponseGenqlSelection & {
+        __args: {
+            input: CreatePartnerBrandSubscriptionInput;
+        };
+    });
     /**
      * Create a moment with optional venue and ticket tiers in one atomic operation.
      * When type is IRL, the venue field is required.
@@ -776,6 +889,12 @@ interface MutationGenqlSelection {
             input: CreatePartnerMomentInput;
         };
     });
+    /** Complete a partner brand subscription that was created with requireOtpVerification=true. */
+    verifyPartnerBrandSubscription?: (BrandSubscriptionGenqlSelection & {
+        __args: {
+            input: VerifyPartnerBrandSubscriptionInput;
+        };
+    });
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
@@ -834,6 +953,13 @@ declare const generateMutationOp: (fields: MutationGenqlSelection & {
     __name?: string;
 }) => GraphqlOperation;
 
+/**
+ * Default ITM backend production API endpoint.
+ */
+declare const DEFAULT_API_URL = "https://itm-backend-production.up.railway.app/graphql";
+type MaybePromise<T> = T | Promise<T>;
+type ITMPartnerHeadersObject = Record<string, string>;
+type ITMPartnerHeaders = ITMPartnerHeadersObject | (() => MaybePromise<ITMPartnerHeadersObject | undefined>);
 interface ITMPartnerClientConfig {
     /**
      * Partner API token (from backstage: Settings > Partner API).
@@ -842,13 +968,15 @@ interface ITMPartnerClientConfig {
     token: string;
     /**
      * Base URL of the ITM GraphQL API.
-     * @default 'https://api.itm.studio/graphql'
+     * @default DEFAULT_API_URL
      */
     baseUrl?: string;
     /**
      * Additional headers to include on every request.
+     * A function is useful for request-scoped values like `x-forwarded-for`
+     * and `user-agent` when proxying end-user traffic through your server.
      */
-    headers?: Record<string, string>;
+    headers?: ITMPartnerHeaders;
 }
 type ITMPartnerClient = Client;
 /**
@@ -881,4 +1009,4 @@ type ITMPartnerClient = Client;
  */
 declare function createITMPartnerClient(config: ITMPartnerClientConfig): ITMPartnerClient;
 
-export { type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type Payment, type PaymentStatus, type Query, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };
+export { type BrandSubscription, type CreatePartnerBrandSubscriptionInput, type CreatePartnerBrandSubscriptionResponse, type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type Currency, DEFAULT_API_URL, type Dimensions, type DimensionsInput, type Echo, type EchoMediaAsset, type EchoType, type GetBrandEchoesForUserResponse, type GetPartnerCustomersResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerClient, type ITMPartnerClientConfig, type ITMPartnerHeaders, type ITMPartnerHeadersObject, type MediaAsset, type MediaAssetUploadUrl, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentType, type Mutation, type PartnerCustomer, type PartnerMomentStats, type Payment, type PaymentStatus, type Query, type SubscriptionComplianceInput, type ThirdPartyEchoType, type Ticket, type TicketExtension, type TicketExtensionStatus, type TicketTier, type User, type Venue, type VenueInput, type VerifyPartnerBrandSubscriptionInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };