@itm-studio/partner-sdk 0.4.0 → 0.4.2

package/README.md

@@ -2165,6 +2165,326 @@ console.log(
 );
 ```
 
+## Login with ITM
+
+Let people sign in to your site with their ITM account. Every sign-in also adds the person to your brand's contacts (source `LOGIN_WITH_ITM`), and both ways of signing in identify the person by the same **customer UID** that `getPartnerAudience` returns. A customer UID is stable for your brand and different for every brand.
+
+There are two ways to run it:
+
+|                                | Hosted sign-in (OpenID Connect)                                       | Custom sign-in form                                                          |
+| ------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Who renders the sign-in screens | ITM, on the app's `issuer` domain, branded with your brand            | Your site                                                                    |
+| How it runs                    | Browser redirect to ITM, then a standard authorization-code exchange  | `startPartnerAppLogin` and `verifyPartnerAppLogin`, from your server         |
+| What you receive               | An ID token and an access token issued by ITM (1 hour, no refresh)    | `customerUid` and a profile. **No token**: you keep your own session         |
+| Partner key used               | Only to register the app                                              | On every call                                                                |
+| Marketing opt-in               | One optional checkbox on ITM's code and "Continue" screens            | One optional checkbox, recorded with the sign-in                             |
+| Person identifier              | The ID token's `sub` claim (equal to the customer UID)                 | `customerUid`                                                                |
+
+Use the hosted sign-in unless you need the form inside your own UI. Both start with an app.
+
+### Register an app
+
+An app is an OpenID Connect client for one of your sites. There are two kinds:
+
+- **Browser app:** a public client with no secret. `createPartnerBrandApp` registers this kind, and it is all the custom sign-in form needs.
+- **Server website:** a confidential client whose server keeps a client secret, so tokens never reach the browser. Create it in Backstage under **Manage › Advanced settings › Login with ITM**. Backstage shows the client secret once and can rotate it.
+
+Register a Browser app once, from your server:
+
+```typescript
+const { createPartnerBrandApp: app } = await itm.mutation({
+  createPartnerBrandApp: {
+    __args: {
+      input: {
+        name: "My site",
+        redirectUris: ["https://example.com/auth/itm"],
+      },
+    },
+    uid: true,
+    clientId: true,
+    redirectUris: true,
+    issuer: true,
+    status: true,
+  },
+});
+```
+
+- `name`: 1 to 80 characters.
+- `redirectUris`: 1 to 10 exact URIs, all on **one origin**, using `https` (`http` is allowed only for `localhost`). No wildcards, fragments or credentials. ITM stores them normalized, so use the strings returned in `app.redirectUris` exactly as your `redirect_uri`. For another site, register another app.
+- The redirect origin is also the only browser origin allowed to call the issuer's token and userinfo endpoints.
+- `clientId` starts with `itm_app_`. It is public, not a secret.
+- `issuer` is the OpenID Connect issuer for the hosted sign-in. It is `null` when hosted sign-in is not configured in that ITM environment; the custom sign-in form still works.
+- A brand can have up to 20 apps. `getPartnerBrandApps` lists them, oldest first.
+- `disablePartnerBrandApp(appUid)` stops new sign-ins through both flows immediately and revokes the app's tokens and remembered consents. A partner key cannot re-enable an app; ask ITM.
+
+Only partner keys can call these five operations. Brand Agent sessions and access tokens cannot.
+
+### Hosted sign-in (OpenID Connect)
+
+Hosted sign-in is standard OpenID Connect, so you do not need this SDK for it, and your partner key is never part of it. Any certified OpenID Connect client library works. The facts a library needs:
+
+- **Discovery:** `${issuer}/.well-known/openid-configuration`. Read the endpoints from it rather than hard-coding paths.
+- **Flow:** authorization code with PKCE. `response_type=code` and `code_challenge_method=S256` are the only values accepted, and PKCE is required.
+- **Client authentication:** a Browser app is a public client with no secret (`token_endpoint_auth_method: none`). A Server website app authenticates with its client secret using `client_secret_basic`.
+- **Scopes:** `openid profile email phone`. Every app gets this fixed set.
+- **ID token:** verify it against the issuer's `jwks_uri`, with `aud` equal to your client ID and the `nonce` you sent. Its `sub` is pairwise: it equals the person's customer UID for your brand.
+- **Profile claims:** read them from the userinfo endpoint with the access token. It returns `name`, `email`, `email_verified`, `phone_number` and `phone_number_verified`, and leaves out any the person does not have. The access token is opaque.
+- **Lifetimes:** authorization codes last 60 seconds; access and ID tokens last 1 hour. There are no refresh tokens (`offline_access` is not supported). When you need new tokens, send the person through the flow again. While their ITM session on the issuer lasts (up to 30 days), a person who already approved your app comes straight back without a prompt.
+- **Revocation** is available. There is no logout endpoint: end your own session.
+
+The person sees your brand's name and logo, gets a code by SMS or email, and approves sharing their name, email address and phone number the first time. They become a contact. They are subscribed to your brand's marketing only if they tick the optional, unticked checkbox on ITM's page.
+
+Run the token exchange on your server and keep tokens out of the browser, following the Backend for Frontend pattern ([RFC 10017 §6.1](https://www.rfc-editor.org/rfc/rfc10017.html)). Prefer an OpenID Connect client library that performs the protocol validation. This framework-neutral sketch with `fetch` and [`jose`](https://github.com/panva/jose) shows the main steps; `rotateSession()` represents your framework's session regeneration API and must invalidate the old session ID and return the new session.
+
+```typescript
+import { createHash, randomBytes } from "node:crypto";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+
+if (!app.issuer) throw new Error("Hosted sign-in is not configured");
+const discoveryResponse = await fetch(`${app.issuer}/.well-known/openid-configuration`);
+if (!discoveryResponse.ok) throw new Error("Discovery failed");
+const discovery = await discoveryResponse.json();
+if (discovery.issuer !== app.issuer) throw new Error("Bad issuer");
+const redirectUri = app.redirectUris[0];
+
+// 1. Send the browser to ITM.
+const login = {
+  verifier: randomBytes(32).toString("base64url"),
+  state: randomBytes(16).toString("base64url"),
+  nonce: randomBytes(16).toString("base64url"),
+};
+session.itmLogin = login;
+const authorize = new URL(discovery.authorization_endpoint);
+authorize.search = new URLSearchParams({
+  client_id: app.clientId,
+  redirect_uri: redirectUri,
+  response_type: "code",
+  scope: "openid profile email phone",
+  state: login.state,
+  nonce: login.nonce,
+  code_challenge: createHash("sha256").update(login.verifier).digest("base64url"),
+  code_challenge_method: "S256",
+}).toString();
+res.redirect(authorize.href);
+
+// 2. On the redirect URI: check state, exchange the code, verify the ID token.
+const pending = session.itmLogin;
+if (!pending || typeof req.query.state !== "string" || req.query.state !== pending.state) {
+  throw new Error("Bad state");
+}
+delete session.itmLogin; // consume and persist this transaction once, including on errors
+if (req.query.error) throw new Error("Sign-in was not completed");
+if (typeof req.query.code !== "string" || !req.query.code) throw new Error("Missing code");
+const tokenResponse = await fetch(discovery.token_endpoint, {
+  method: "POST",
+  headers: { "content-type": "application/x-www-form-urlencoded" },
+  body: new URLSearchParams({
+    grant_type: "authorization_code",
+    code: req.query.code,
+    redirect_uri: redirectUri,
+    client_id: app.clientId,
+    code_verifier: pending.verifier,
+  }),
+});
+if (!tokenResponse.ok) throw new Error("Token exchange failed");
+const tokens = await tokenResponse.json();
+const { payload } = await jwtVerify(
+  tokens.id_token,
+  createRemoteJWKSet(new URL(discovery.jwks_uri)),
+  {
+    issuer: app.issuer,
+    audience: app.clientId,
+    algorithms: ["RS256"], // ITM's registered default ID-token signing algorithm
+    requiredClaims: ["sub", "iat", "exp", "nonce"],
+  },
+);
+if (payload.nonce !== pending.nonce) throw new Error("Bad nonce");
+if (typeof payload.sub !== "string" || !payload.sub) throw new Error("Missing subject");
+if ((Array.isArray(payload.aud) && payload.aud.length > 1 && !payload.azp) ||
+    (payload.azp !== undefined && payload.azp !== app.clientId)) {
+  throw new Error("Bad authorized party");
+}
+
+// 3. Optional: read the profile.
+const profileResponse = await fetch(discovery.userinfo_endpoint, {
+  headers: { authorization: `Bearer ${tokens.access_token}` },
+});
+if (!profileResponse.ok) throw new Error("Profile request failed");
+const profile = await profileResponse.json();
+if (profile.sub !== payload.sub) throw new Error("Profile subject mismatch");
+
+// Only establish the authenticated session after all checks succeed.
+const authenticatedSession = await rotateSession();
+authenticatedSession.customerUid = payload.sub;
+```
+
+The sketch uses a Browser app. With a Server website app, also authenticate the token request with `client_secret_basic` (an `authorization: Basic …` header built from the client ID and client secret) and keep the secret on your server. For a complete server example using `openid-client`, see [`examples/login-with-itm`](https://github.com/itm-studio/demo-events-sdk-integration/tree/main/examples/login-with-itm).
+
+A redirect that comes back with `error=access_denied` means the person cancelled.
+Never use UserInfo claims until its `sub` matches the validated ID token's `sub` ([OpenID Connect Core §5.3.2](https://openid.net/specs/openid-connect-core-1_0.html#UserInfoResponse)). Persist the pending login before redirecting, expire it after a short interval, and consume it once on callback using your session store's concurrency controls.
+
+### Custom sign-in form
+
+Your site renders the sign-in form. ITM sends and checks the code, finds or creates the person's ITM account, and adds them to your brand's contacts, optionally with a marketing opt-in. Both calls run **from your server** with your partner key.
+
+#### Step 1: send a code
+
+```typescript
+const { startPartnerAppLogin: challenge } = await itm.mutation({
+  startPartnerAppLogin: {
+    __args: {
+      input: {
+        clientId: app.clientId,
+        identifier, // phone number or email address the visitor typed
+        compliance: {
+          ipAddress: visitorIp, // required: the visitor's IP, not your server's
+          userAgent: req.headers["user-agent"],
+          pageUrl: "https://example.com/login",
+        },
+      },
+    },
+    channel: true,
+    destinationHint: true,
+    expiresAt: true,
+    disclosure: true,
+    marketingConsentPrompt: {
+      promptUid: true,
+      labelMarkdown: true,
+      bodyMarkdown: true,
+      channels: true,
+    },
+  },
+});
+session.itmLoginIdentifier = identifier; // keep it server-side for step 3
+```
+
+- `identifier`: an email address, or a phone number in E.164 (`+14155550142`). A number without a country code is read as a US number.
+- `compliance.ipAddress` is required on both steps. Unlike partner subscriptions, sign-in does **not** fill it in from forwarded headers.
+- `channel` is `EMAIL` for email addresses. For phone numbers it is usually `SMS`, but ITM's delivery checks can send the code by `WHATSAPP` or a voice `CALL` instead. Tell the visitor where to look.
+- `destinationHint` is the masked phone number or email address to show, and `expiresAt` is when the code stops working (10 minutes).
+- The response is the same whether or not the person already has an ITM account, so it cannot be used to discover accounts.
+
+#### Step 2: show the code field
+
+Render on the same screen:
+
+- `challenge.disclosure`, verbatim. It tells the visitor what signing in shares with you.
+- `challenge.marketingConsentPrompt` as **one optional, unchecked** checkbox: `labelMarkdown` as its label and `bodyMarkdown` below it. Signing in must not depend on it. It covers SMS and email marketing from your brand via ITM.
+
+#### Step 3: verify
+
+```typescript
+const { verifyPartnerAppLogin: login } = await itm.mutation({
+  verifyPartnerAppLogin: {
+    __args: {
+      input: {
+        clientId: app.clientId,
+        identifier: session.itmLoginIdentifier, // never from the browser
+        code, // 6 digits; spaces are ignored
+        compliance: { ipAddress: visitorIp, userAgent: req.headers["user-agent"] },
+        // Only when the box was ticked; omitting it never unsubscribes anyone.
+        // pageUrl is required with an opt-in (here or in compliance).
+        ...(optedIn
+          ? { marketingConsent: { accepted: true, pageUrl: "https://example.com/login" } }
+          : {}),
+      },
+    },
+    customerUid: true,
+    profile: {
+      name: true,
+      email: true,
+      emailVerified: true,
+      phoneNumber: true,
+      phoneVerified: true,
+    },
+  },
+});
+delete session.itmLoginIdentifier;
+const authenticatedSession = await rotateSession(); // invalidate the old session ID
+authenticatedSession.customerUid = login.customerUid;
+```
+
+The response is **not a credential**. ITM issues no token in this flow: keep your own session, keyed by `customerUid`. The same person signing in again gets the same `customerUid`; `profile` reflects their ITM account at that moment, and fields they have not provided are `null`.
+
+#### Errors
+
+Every failure throws a `GenqlError`. Its `errors[0].message` is the text below and `errors[0].extensions.code` is the code:
+
+| Situation | Operation | `code` | `message` |
+| --- | --- | --- | --- |
+| No partner key, or an invalid one | all | `UNAUTHENTICATED` | `No partner access token provided…` or an invalid-token message |
+| `clientId` is unknown, belongs to another brand, or the app is disabled | start, verify | `NOT_FOUND` | `App not found` |
+| `appUid` is unknown or belongs to another brand | disable | `NOT_FOUND` | `App not found` |
+| `identifier` is neither a phone number nor an email address | start, verify | `BAD_USER_INPUT` | `Enter a valid phone number or email address` |
+| `compliance.ipAddress` is missing or not an IP address | start, verify | `BAD_USER_INPUT` | `compliance.ipAddress must be the visitor's IP address` |
+| A code was sent to this person for this app less than a minute ago. The earlier code still works | start | `RATE_LIMITED` | `A code was already requested. Wait a minute before requesting another.` |
+| Too many codes sent to this person, or by your brand today | start | `RATE_LIMITED` | `Too many attempts. Wait a few minutes and try again.` |
+| Too many codes sent to this email address or from this IP | start | `BAD_USER_INPUT` | `Too many verification code requests` |
+| ITM does not send codes to this phone number | start | `BAD_USER_INPUT` | `Verification is not available for this phone number.` |
+| ITM's SMS fraud limits for this number or IP, or a temporary SMS outage | start, verify (phone) | `BAD_USER_INPUT` | `Too many verification requests. Please wait before trying again.` or `Verification is temporarily unavailable. Please try again shortly.` |
+| Wrong code, or a code requested with a different partner key | verify | `BAD_USER_INPUT` | `Invalid verification code` |
+| The code expired, was already used, or was never sent | verify | `BAD_USER_INPUT` | `Invalid or expired verification code` |
+| Fifth wrong code. The code is discarded; send a new one | verify | `BAD_USER_INPUT` | `Too many attempts. Request a new code.` |
+| Too many verification attempts for this person | verify | `RATE_LIMITED` | `Too many attempts. Wait a few minutes and try again.` |
+| `marketingConsent.accepted` without a `pageUrl`. The code is not used up | verify | `BAD_USER_INPUT` | `pageUrl is required when the visitor opts in` |
+| The account cannot sign in (for example an imported contact that never signed up). Nothing is recorded | verify | `BAD_USER_INPUT` | `This account can't be used to log in here. Contact ITM support.` |
+| More requests per minute than your key's limit | all | `RATE_LIMITED` | varies |
+
+```typescript
+import { GenqlError } from "@itm-studio/partner-sdk";
+
+try {
+  await itm.mutation({ verifyPartnerAppLogin: { /* … */ } });
+} catch (error) {
+  if (error instanceof GenqlError) {
+    const [first] = error.errors;
+    // Show first.message to the visitor; branch on first.extensions?.code.
+  }
+  throw error;
+}
+```
+
+#### Limits
+
+| Limit | Value |
+| --- | --- |
+| Code lifetime | 10 minutes |
+| New code for the same person and app | after 1 minute |
+| Wrong codes per code | 5 |
+| Codes sent to one phone number or email address | 5 per 10 minutes, shared with hosted sign-in |
+| Codes sent by one brand | 2,000 per 24 hours |
+| Email codes | 5 per hour and 10 per day per address; 30 per hour per visitor IP |
+| Verification attempts per person and app | 10 per 15 minutes |
+| `startPartnerAppLogin`, `verifyPartnerAppLogin` | 30 requests per minute per partner key |
+| `createPartnerBrandApp`, `disablePartnerBrandApp` | 20 requests per minute per partner key |
+| `getPartnerBrandApps` | 120 requests per minute per partner key |
+
+### Marketing opt-in at sign-in
+
+When the visitor ticks the checkbox from step 2 and you send `marketingConsent: { accepted: true }`:
+
+- ITM stores the opt-in as consent evidence: the prompt text it supplied, the time, the visitor's IP address and user agent, and the page URL.
+- Shortly after the sign-in completes, ITM subscribes the person to your brand for SMS and email marketing. This runs asynchronously, so it is not reflected in the `verifyPartnerAppLogin` response.
+- Each opt-in is recorded as new evidence, including repeat opt-ins. Leaving the box unticked records nothing and never unsubscribes anyone.
+- People your brand has blacklisted can still sign in, but an opt-in never subscribes them.
+
+Hosted sign-in offers the same optional checkbox on ITM's code and "Continue to {Brand}" screens, and ITM records a ticked box as an opt-in. To subscribe someone outside sign-in, collect consent on your own page and call `createPartnerBrandSubscription`; see the [Partner Brand Subscription Guide](#partner-brand-subscription-guide).
+
+### What ITM handles
+
+- Codes only work for the app and the partner key that requested them. They cannot sign anyone in to ITM itself or to another app.
+- New and returning people get identical responses until the code is verified.
+- The person becomes a contact and is **not** subscribed to marketing unless they opted in.
+
+### What your site must do
+
+- Keep the partner key and both custom-form calls on your server, and keep hosted sign-in tokens there too.
+- Read `identifier` for step 3 from your own session, not from the browser.
+- Pass the visitor's real IP address on both steps of the custom form.
+- Store your session in `Secure`, `HttpOnly`, `SameSite` cookies, as in the Backend for Frontend pattern ([RFC 10017 §6.1](https://www.rfc-editor.org/rfc/rfc10017.html)).
+- Regenerate the session ID after either sign-in flow succeeds, invalidate the old session, and clear pending login state. Use your framework's session API for the `rotateSession()` placeholder above.
+- Protect your send-code and verify endpoints with CSRF tokens and your own bot protection.
+
 ## Pagination
 
 All list endpoints use cursor-based pagination. The default page size is **50** items if `take` is not specified.
@@ -2198,7 +2518,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.itm-api.com/graphql",
 });
 ```
 

package/dist/index.d.mts

@@ -902,7 +902,63 @@ interface PartnerMembershipTier {
     yearlyPrice: (Scalars['Int'] | null);
     __typename: 'PartnerMembershipTier';
 }
+/** Whether a Login with ITM app can sign users in. */
+type BrandAppStatus = 'ACTIVE' | 'DISABLED';
+type ConsentChannel = 'EMAIL' | 'PUSH' | 'SMS';
+type ConsentPromptCategory = 'CUSTOM' | 'MARKETING' | 'PRIVACY' | 'TERMS';
+type LoginCodeChannel = 'CALL' | 'EMAIL' | 'SMS' | 'WHATSAPP';
+/** A brand-owned Login with ITM application: a public OAuth/OIDC client that uses PKCE and has no secret. */
+interface BrandApp {
+    /** Public OAuth client_id. It is not a secret. */
+    clientId: Scalars['String'];
+    createdAt: Scalars['DateTime'];
+    /** OpenID Connect issuer URL apps authenticate against; null when Login with ITM is not configured. */
+    issuer: (Scalars['String'] | null);
+    name: Scalars['String'];
+    /** Exact redirect URIs. All share one origin; that origin may call the token and userinfo endpoints and hand logins to ITM embeds. */
+    redirectUris: Scalars['String'][];
+    status: BrandAppStatus;
+    uid: Scalars['String'];
+    __typename: 'BrandApp';
+}
+interface CheckoutMarketingConsentPrompt {
+    bodyMarkdown: (Scalars['String'] | null);
+    category: ConsentPromptCategory;
+    channels: ConsentChannel[];
+    labelMarkdown: Scalars['String'];
+    promptUid: Scalars['String'];
+    required: Scalars['Boolean'];
+    version: Scalars['Int'];
+    __typename: 'CheckoutMarketingConsentPrompt';
+}
+interface PartnerAppLoginChallenge {
+    channel: LoginCodeChannel;
+    destinationHint: (Scalars['String'] | null);
+    /** Show this text verbatim with the code field: it is what signing in shares. */
+    disclosure: Scalars['String'];
+    expiresAt: Scalars['DateTime'];
+    /** Optional marketing opt-in. Render verbatim as an unchecked checkbox; signing in must not depend on it. */
+    marketingConsentPrompt: CheckoutMarketingConsentPrompt;
+    __typename: 'PartnerAppLoginChallenge';
+}
+interface PartnerAppLoginProfile {
+    email: (Scalars['String'] | null);
+    emailVerified: Scalars['Boolean'];
+    name: (Scalars['String'] | null);
+    phoneNumber: (Scalars['String'] | null);
+    phoneVerified: Scalars['Boolean'];
+    __typename: 'PartnerAppLoginProfile';
+}
+/** A completed headless sign-in. It is not a credential: keep your own session keyed by customerUid. */
+interface PartnerAppLogin {
+    /** The person's customer UID for your brand (getPartnerAudience customer uid). */
+    customerUid: Scalars['String'];
+    profile: PartnerAppLoginProfile;
+    __typename: 'PartnerAppLogin';
+}
 interface Query {
+    /** The brand's Login with ITM apps (at most 20), oldest first. Deleted apps are omitted. */
+    getPartnerBrandApps: BrandApp[];
     /** List the authenticated partner brand's membership rows; PENDING is excluded by default. */
     getPartnerMembers: GetPartnerMembersResponse;
     /** List the authenticated partner brand's non-deleted membership tiers, including inactive and private tiers. */
@@ -1057,6 +1113,14 @@ interface CreatePartnerBrandSubscriptionResponse {
     __typename: 'CreatePartnerBrandSubscriptionResponse';
 }
 interface Mutation {
+    /** Registers a Login with ITM app for the brand. A brand can have up to 20 apps. */
+    createPartnerBrandApp: BrandApp;
+    /** Disables an app: new logins stop and its tokens and remembered consents are revoked immediately. A partner key cannot re-enable it; ask ITM. */
+    disablePartnerBrandApp: BrandApp;
+    /** Sends a Login with ITM code for the brand's own sign-in form. Call it from your server; the response is the same whether or not the person has an ITM account. */
+    startPartnerAppLogin: PartnerAppLoginChallenge;
+    /** Completes a headless sign-in: checks the code, adds the person to the brand's contacts and records an optional opt-in. Returns no ITM credential. */
+    verifyPartnerAppLogin: PartnerAppLogin;
     /** Log a payment received off-site. Brand scope comes from the authenticated token or agent session. Amount is in ITM cents (major units times 100). Retain requestUid across retries. */
     createPartnerManualContribution: ContributionAdmin;
     reserveAgentMediaUpload: AgentMediaUploadReservation;
@@ -2319,7 +2383,97 @@ interface PartnerMembershipTierGenqlSelection {
     __typename?: boolean | number;
     __scalar?: boolean | number;
 }
+/** A brand-owned Login with ITM application: a public OAuth/OIDC client that uses PKCE and has no secret. */
+interface BrandAppGenqlSelection {
+    /** Public OAuth client_id. It is not a secret. */
+    clientId?: boolean | number;
+    createdAt?: boolean | number;
+    /** OpenID Connect issuer URL apps authenticate against; null when Login with ITM is not configured. */
+    issuer?: boolean | number;
+    name?: boolean | number;
+    /** Exact redirect URIs. All share one origin; that origin may call the token and userinfo endpoints and hand logins to ITM embeds. */
+    redirectUris?: boolean | number;
+    status?: boolean | number;
+    uid?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+interface CreateBrandAppInput {
+    name: Scalars['String'];
+    /** Exact https redirect URIs (http is allowed only for localhost) on a single origin. */
+    redirectUris: Scalars['String'][];
+}
+interface CheckoutMarketingConsentPromptGenqlSelection {
+    bodyMarkdown?: boolean | number;
+    category?: boolean | number;
+    channels?: boolean | number;
+    labelMarkdown?: boolean | number;
+    promptUid?: boolean | number;
+    required?: boolean | number;
+    version?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+interface CheckoutMarketingConsentInput {
+    accepted: Scalars['Boolean'];
+    language?: (Scalars['String'] | null);
+    pageUrl?: (Scalars['String'] | null);
+    referrerUrl?: (Scalars['String'] | null);
+    screenHeight?: (Scalars['Int'] | null);
+    screenWidth?: (Scalars['Int'] | null);
+    submittedAt?: (Scalars['DateTime'] | null);
+    timezone?: (Scalars['String'] | null);
+}
+/** Starts a headless Login with ITM sign-in from the brand's server: ITM sends a code that only verifyPartnerAppLogin accepts for this app and partner credential. */
+interface StartPartnerAppLoginInput {
+    /** The app's public client ID. */
+    clientId: Scalars['String'];
+    /** The visitor's request details. ipAddress (the visitor's, not your server's) is required. */
+    compliance: SubscriptionComplianceInput;
+    /** Phone number or email address. */
+    identifier: Scalars['String'];
+}
+interface PartnerAppLoginChallengeGenqlSelection {
+    channel?: boolean | number;
+    destinationHint?: boolean | number;
+    /** Show this text verbatim with the code field: it is what signing in shares. */
+    disclosure?: boolean | number;
+    expiresAt?: boolean | number;
+    /** Optional marketing opt-in. Render verbatim as an unchecked checkbox; signing in must not depend on it. */
+    marketingConsentPrompt?: CheckoutMarketingConsentPromptGenqlSelection;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+interface VerifyPartnerAppLoginInput {
+    clientId: Scalars['String'];
+    code: Scalars['String'];
+    /** The visitor's request details. ipAddress is required. */
+    compliance: SubscriptionComplianceInput;
+    /** The identifier the code was sent to. Read it from your own session, not from the browser. */
+    identifier: Scalars['String'];
+    /** Send only when the visitor ticked the opt-in (accepted: true; pageUrl here or in compliance). Omit it otherwise; omission never unsubscribes anyone. */
+    marketingConsent?: (CheckoutMarketingConsentInput | null);
+}
+interface PartnerAppLoginProfileGenqlSelection {
+    email?: boolean | number;
+    emailVerified?: boolean | number;
+    name?: boolean | number;
+    phoneNumber?: boolean | number;
+    phoneVerified?: boolean | number;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
+/** A completed headless sign-in. It is not a credential: keep your own session keyed by customerUid. */
+interface PartnerAppLoginGenqlSelection {
+    /** The person's customer UID for your brand (getPartnerAudience customer uid). */
+    customerUid?: boolean | number;
+    profile?: PartnerAppLoginProfileGenqlSelection;
+    __typename?: boolean | number;
+    __scalar?: boolean | number;
+}
 interface QueryGenqlSelection {
+    /** The brand's Login with ITM apps (at most 20), oldest first. Deleted apps are omitted. */
+    getPartnerBrandApps?: BrandAppGenqlSelection;
     /** List the authenticated partner brand's membership rows; PENDING is excluded by default. */
     getPartnerMembers?: (GetPartnerMembersResponseGenqlSelection & {
         __args?: {
@@ -2914,6 +3068,30 @@ interface CreatePartnerBrandSubscriptionResponseGenqlSelection {
     __scalar?: boolean | number;
 }
 interface MutationGenqlSelection {
+    /** Registers a Login with ITM app for the brand. A brand can have up to 20 apps. */
+    createPartnerBrandApp?: (BrandAppGenqlSelection & {
+        __args: {
+            input: CreateBrandAppInput;
+        };
+    });
+    /** Disables an app: new logins stop and its tokens and remembered consents are revoked immediately. A partner key cannot re-enable it; ask ITM. */
+    disablePartnerBrandApp?: (BrandAppGenqlSelection & {
+        __args: {
+            appUid: Scalars['String'];
+        };
+    });
+    /** Sends a Login with ITM code for the brand's own sign-in form. Call it from your server; the response is the same whether or not the person has an ITM account. */
+    startPartnerAppLogin?: (PartnerAppLoginChallengeGenqlSelection & {
+        __args: {
+            input: StartPartnerAppLoginInput;
+        };
+    });
+    /** Completes a headless sign-in: checks the code, adds the person to the brand's contacts and records an optional opt-in. Returns no ITM credential. */
+    verifyPartnerAppLogin?: (PartnerAppLoginGenqlSelection & {
+        __args: {
+            input: VerifyPartnerAppLoginInput;
+        };
+    });
     /** Log a payment received off-site. Brand scope comes from the authenticated token or agent session. Amount is in ITM cents (major units times 100). Retain requestUid across retries. */
     createPartnerManualContribution?: (ContributionAdminGenqlSelection & {
         __args: {
@@ -3553,4 +3731,4 @@ type ITMPartnerClient = Client;
  */
 declare function createITMPartnerClient(config: ITMPartnerClientConfig): ITMPartnerClient;
 
-export { type AgentThreadSeedContext, type ApplyDynamicPricingInput, type BrandAgentEmailMessageInput, type BrandAgentEmailSendBatch, type BrandAgentEmailSendBatchStatus, type BrandAgentEmailSendMessage, type BrandAgentEmailSendMessageStatus, type BrandDrop, type BrandDropCtaType, type BrandDropMusicLink, type BrandSubscription, type ConsentStatus, type ContributionAdmin, type ContributionPageAdmin, type ContributionPageStatusFilter, type ContributionPagesResponse, type ContributionSource, type ContributionStatus, type ContributionsResponse, type CreateManualContributionInput, type CreateMomentOnlineConfigInput, type CreatePartnerBrandDropInput, type CreatePartnerBrandSubscriptionInput, type CreatePartnerBrandSubscriptionResponse, type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type CreatePlanBudgetInput, type CreatePlanInput, type Currency, DEFAULT_API_URL, type Dimensions, type DimensionsInput, type DynamicPricingActorType, type DynamicPricingAdmissionWindow, type DynamicPricingBatch, type DynamicPricingBatchEvent, type DynamicPricingBatchEventType, type DynamicPricingBatchItem, type DynamicPricingBatchItemStatus, type DynamicPricingBatchStatus, type DynamicPricingContext, type DynamicPricingExecutionMode, type DynamicPricingInventoryGuardInput, type DynamicPricingInventoryGuardMode, type DynamicPricingInventoryMetric, type DynamicPricingMomentInput, type DynamicPricingTierContext, type DynamicPricingTierUpdateInput, type Echo, type EchoMediaAsset, type EchoType, type EditPartnerTicketTiersForMomentInput, type EventImportPlatform, GenqlError, type GetBrandEchoesForUserResponse, type GetMomentLineupsResponse, type GetMomentTagAssignmentsResponse, type GetPartnerAudienceInput, type GetPartnerAudienceResponse, type GetPartnerCustomersResponse, type GetPartnerDropsResponse, type GetPartnerMediaAssetsInput, type GetPartnerMediaAssetsResponse, type GetPartnerMembersInput, type GetPartnerMembersResponse, type GetPartnerMembershipTiersInput, type GetPartnerMembershipTiersResponse, type GetPartnerTicketTiersForMomentInput, type GetPartnerTicketTiersForMomentResponse, type GetPlansInput, type GetPlansResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerAgentAccessConfig, type ITMPartnerAgentAccessCredentials, type ITMPartnerAgentSessionConfig, type ITMPartnerAgentSessionCredentials, type ITMPartnerClient, type ITMPartnerClientConfig, type ITMPartnerHeaders, type ITMPartnerHeadersObject, type ITMPartnerTokenConfig, type ManualContributionReceiptType, type MediaAsset, type MediaAssetUploadUrl, type MembershipBillingInterval, type MembershipExpiryType, type MembershipPassType, type MembershipPurchaseType, type MembershipSource, type MembershipStatus, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentDynamicPricingPolicy, type MomentDynamicPricingTierRule, type MomentLineup, type MomentLineupDisplayLabel, type MomentLineupResponseResult, type MomentLineupStatus, type MomentLineupType, type MomentOccurrenceScheduleFrequency, type MomentOnlineProvider, type MomentPublicVenuePreview, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentTagAssignment, type MomentType, type MusicReleaseType, type Mutation, type PaginationInput, type PartnerAudienceCustomer, type PartnerAudienceFiltersInput, type PartnerAudienceSortField, type PartnerAudienceSortInput, type PartnerBrand, type PartnerCustomer, type PartnerMember, type PartnerMemberCustomer, type PartnerMemberTier, type PartnerMembershipTier, type PartnerMomentAttendanceCount, type PartnerMomentAttendanceLookupInput, type PartnerMomentAttendanceStats, type PartnerMomentGuestlistAttendance, type PartnerMomentGuestlistLabelAttendance, type PartnerMomentStats, type PartnerMomentTicketAttendance, type PartnerMomentTicketTierAttendance, type PartnerMomentsFiltersInput, type PartnerTicketStatus, type PartnerTicketTier, type PartnerTicketTierUpdateInput, type PartnerTicketUserLookupInput, type PartnerTicketsForUserInput, type Payment, type PaymentStatus, type Plan, type PlanBudget, type PlanBudgetAllocationType, type PlanBudgetArtistDealBasis, type PlanBudgetArtistDealInput, type PlanBudgetArtistDealType, type PlanBudgetCapacityAllocationInput, type PlanBudgetCategoryInput, type PlanBudgetCategoryKind, type PlanBudgetChargeCalculation, type PlanBudgetChargeKind, type PlanBudgetChargeTreatment, type PlanBudgetExternalTicketingChannelInput, type PlanBudgetFeeAssessment, type PlanBudgetFeeComponentKind, type PlanBudgetFeePercentageBasis, type PlanBudgetGuaranteeBasis, type PlanBudgetLineBasis, type PlanBudgetLineInput, type PlanBudgetPaymentStatus, type PlanBudgetPricingMode, type PlanBudgetSummary, type PlanBudgetTicketChargeRuleInput, type PlanBudgetTicketTierInput, type PlanBudgetTicketingChannelType, type PlanBudgetTicketingFeeComponentInput, type PlanKind, type PlanLinkMetadataStatus, type PlanMoodboard, type PlanMoodboardItem, type PlanMoodboardItemType, type PlanSchedule, type PlanScheduleInput, type PlanScheduleTime, type PlanScheduleTimeInput, type PlanScheduleType, type PlanStatus, type PlanSummary, type PlanningProposal, type PlanningSource, type PlanningSourceDispositionInput, type PlanningSourceSection, type PostSubscriptionEmailInput, type PostSubscriptionMessageInput, type PostSubscriptionPushInput, type PostSubscriptionSmsInput, type PreparePlanningProposalInput, type PublicMomentLineupInfo, type Query, type ReplacePlanBudgetDraftInput, type RespondToMomentLineupInput, type SendPartnerAgentEmailInput, type SortDirection, type SubscriptionComplianceInput, type Tag, type TagSource, type ThirdPartyEchoType, type Ticket, type TicketAdmissionWindowSource, type TicketAttendanceMode, type TicketExtension, type TicketExtensionStatus, type TicketTier, type Transforms, type UpdatePlanInput, type User, type UserSource, type Venue, type VenueInput, type VerifyPartnerBrandSubscriptionInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };
+export { type AgentThreadSeedContext, type ApplyDynamicPricingInput, type BrandAgentEmailMessageInput, type BrandAgentEmailSendBatch, type BrandAgentEmailSendBatchStatus, type BrandAgentEmailSendMessage, type BrandAgentEmailSendMessageStatus, type BrandApp, type BrandAppStatus, type BrandDrop, type BrandDropCtaType, type BrandDropMusicLink, type BrandSubscription, type CheckoutMarketingConsentInput, type CheckoutMarketingConsentPrompt, type ConsentChannel, type ConsentPromptCategory, type ConsentStatus, type ContributionAdmin, type ContributionPageAdmin, type ContributionPageStatusFilter, type ContributionPagesResponse, type ContributionSource, type ContributionStatus, type ContributionsResponse, type CreateBrandAppInput, type CreateManualContributionInput, type CreateMomentOnlineConfigInput, type CreatePartnerBrandDropInput, type CreatePartnerBrandSubscriptionInput, type CreatePartnerBrandSubscriptionResponse, type CreatePartnerMomentInput, type CreatePartnerTicketTierInput, type CreatePlanBudgetInput, type CreatePlanInput, type Currency, DEFAULT_API_URL, type Dimensions, type DimensionsInput, type DynamicPricingActorType, type DynamicPricingAdmissionWindow, type DynamicPricingBatch, type DynamicPricingBatchEvent, type DynamicPricingBatchEventType, type DynamicPricingBatchItem, type DynamicPricingBatchItemStatus, type DynamicPricingBatchStatus, type DynamicPricingContext, type DynamicPricingExecutionMode, type DynamicPricingInventoryGuardInput, type DynamicPricingInventoryGuardMode, type DynamicPricingInventoryMetric, type DynamicPricingMomentInput, type DynamicPricingTierContext, type DynamicPricingTierUpdateInput, type Echo, type EchoMediaAsset, type EchoType, type EditPartnerTicketTiersForMomentInput, type EventImportPlatform, GenqlError, type GetBrandEchoesForUserResponse, type GetMomentLineupsResponse, type GetMomentTagAssignmentsResponse, type GetPartnerAudienceInput, type GetPartnerAudienceResponse, type GetPartnerCustomersResponse, type GetPartnerDropsResponse, type GetPartnerMediaAssetsInput, type GetPartnerMediaAssetsResponse, type GetPartnerMembersInput, type GetPartnerMembersResponse, type GetPartnerMembershipTiersInput, type GetPartnerMembershipTiersResponse, type GetPartnerTicketTiersForMomentInput, type GetPartnerTicketTiersForMomentResponse, type GetPlansInput, type GetPlansResponse, type GetPublicMomentsResponse, type GetTicketsResponse, type ITMPartnerAgentAccessConfig, type ITMPartnerAgentAccessCredentials, type ITMPartnerAgentSessionConfig, type ITMPartnerAgentSessionCredentials, type ITMPartnerClient, type ITMPartnerClientConfig, type ITMPartnerHeaders, type ITMPartnerHeadersObject, type ITMPartnerTokenConfig, type LoginCodeChannel, type ManualContributionReceiptType, type MediaAsset, type MediaAssetUploadUrl, type MembershipBillingInterval, type MembershipExpiryType, type MembershipPassType, type MembershipPurchaseType, type MembershipSource, type MembershipStatus, type MerchPurchase, type Moment, type MomentCategory, type MomentCollection, type MomentCollectionLink, type MomentDiscountCodeUsage, type MomentDynamicPricingPolicy, type MomentDynamicPricingTierRule, type MomentLineup, type MomentLineupDisplayLabel, type MomentLineupResponseResult, type MomentLineupStatus, type MomentLineupType, type MomentOccurrenceScheduleFrequency, type MomentOnlineProvider, type MomentPublicVenuePreview, type MomentSortOrder, type MomentStatus, type MomentSubcategory, type MomentTagAssignment, type MomentType, type MusicReleaseType, type Mutation, type PaginationInput, type PartnerAppLogin, type PartnerAppLoginChallenge, type PartnerAppLoginProfile, type PartnerAudienceCustomer, type PartnerAudienceFiltersInput, type PartnerAudienceSortField, type PartnerAudienceSortInput, type PartnerBrand, type PartnerCustomer, type PartnerMember, type PartnerMemberCustomer, type PartnerMemberTier, type PartnerMembershipTier, type PartnerMomentAttendanceCount, type PartnerMomentAttendanceLookupInput, type PartnerMomentAttendanceStats, type PartnerMomentGuestlistAttendance, type PartnerMomentGuestlistLabelAttendance, type PartnerMomentStats, type PartnerMomentTicketAttendance, type PartnerMomentTicketTierAttendance, type PartnerMomentsFiltersInput, type PartnerTicketStatus, type PartnerTicketTier, type PartnerTicketTierUpdateInput, type PartnerTicketUserLookupInput, type PartnerTicketsForUserInput, type Payment, type PaymentStatus, type Plan, type PlanBudget, type PlanBudgetAllocationType, type PlanBudgetArtistDealBasis, type PlanBudgetArtistDealInput, type PlanBudgetArtistDealType, type PlanBudgetCapacityAllocationInput, type PlanBudgetCategoryInput, type PlanBudgetCategoryKind, type PlanBudgetChargeCalculation, type PlanBudgetChargeKind, type PlanBudgetChargeTreatment, type PlanBudgetExternalTicketingChannelInput, type PlanBudgetFeeAssessment, type PlanBudgetFeeComponentKind, type PlanBudgetFeePercentageBasis, type PlanBudgetGuaranteeBasis, type PlanBudgetLineBasis, type PlanBudgetLineInput, type PlanBudgetPaymentStatus, type PlanBudgetPricingMode, type PlanBudgetSummary, type PlanBudgetTicketChargeRuleInput, type PlanBudgetTicketTierInput, type PlanBudgetTicketingChannelType, type PlanBudgetTicketingFeeComponentInput, type PlanKind, type PlanLinkMetadataStatus, type PlanMoodboard, type PlanMoodboardItem, type PlanMoodboardItemType, type PlanSchedule, type PlanScheduleInput, type PlanScheduleTime, type PlanScheduleTimeInput, type PlanScheduleType, type PlanStatus, type PlanSummary, type PlanningProposal, type PlanningSource, type PlanningSourceDispositionInput, type PlanningSourceSection, type PostSubscriptionEmailInput, type PostSubscriptionMessageInput, type PostSubscriptionPushInput, type PostSubscriptionSmsInput, type PreparePlanningProposalInput, type PublicMomentLineupInfo, type Query, type ReplacePlanBudgetDraftInput, type RespondToMomentLineupInput, type SendPartnerAgentEmailInput, type SortDirection, type StartPartnerAppLoginInput, type SubscriptionComplianceInput, type Tag, type TagSource, type ThirdPartyEchoType, type Ticket, type TicketAdmissionWindowSource, type TicketAttendanceMode, type TicketExtension, type TicketExtensionStatus, type TicketTier, type Transforms, type UpdatePlanInput, type User, type UserSource, type Venue, type VenueInput, type VerifyPartnerAppLoginInput, type VerifyPartnerBrandSubscriptionInput, createITMPartnerClient, everything, generateMutationOp, generateQueryOp };