@itm-studio/partner-sdk 0.3.6 → 0.3.8

package/README.md

@@ -47,6 +47,11 @@ const { getPartnerMomentsForBrand } = await itm.query({
         city: true,
         country: true,
       },
+      publicVenuePreview: {
+        city: true,
+        country: true,
+        countryCode: true,
+      },
       ticketTiers: {
         name: true,
         price: true,
@@ -647,6 +652,11 @@ const { getPartnerMoment } = await itm.query({
       city: true,
       postalCode: true,
     },
+    publicVenuePreview: {
+      city: true,
+      country: true,
+      countryCode: true,
+    },
     ticketTiers: {
       name: true,
       price: true,
@@ -656,6 +666,15 @@ const { getPartnerMoment } = await itm.query({
 });
 ```
 
+`Moment.venue` returns full venue details and is nullable. For public location
+text, select `Moment.publicVenuePreview`: it returns `city`, a display `country`
+label, and nullable `countryCode`, without the venue name or street address. It
+remains available when the venue is hidden until RSVP, and returns `null` when
+no venue is set. The API field is named `publicVenuePreview`.
+
+The same selection works wherever the API returns a `Moment`, including
+`getPartnerMomentsForBrand.moments` and `Ticket.moment`.
+
 ### `getPublicMomentLineups`
 
 Get approved public lineup entries for a moment. Use `getPartnerMoment` first if you only have the moment slug; this query takes the moment `uid`.
@@ -860,13 +879,20 @@ Supported filters include `ticketTierUids`, `search`, `isActive`, `isPrivate`,
 
 ### `getPartnerTicketsForMoment`
 
-Get paginated tickets for a moment.
+Get confirmed tickets for a moment owned by your partner token's brand. The
+`user` filter matches the current ITM account holding the ticket, rather than
+guest contact details entered at checkout. Provide exactly one of `userUid`,
+`email`, or `phoneNumber`. An unknown account returns an empty ticket page.
+
+`take` defaults to 50 and is capped at 100. Continue with `nextCursor` while
+`hasNextPage` is true to retrieve all tickets.
 
 ```typescript
 const { getPartnerTicketsForMoment } = await itm.query({
   getPartnerTicketsForMoment: {
     __args: {
       momentSlug: "my-event-slug",
+      user: { userUid: "customer-uid" }, // optional: exactly one of userUid, email, phoneNumber
       checkedIn: true, // optional: filter by check-in status
       take: 50,
     },
@@ -874,6 +900,7 @@ const { getPartnerTicketsForMoment } = await itm.query({
       uid: true,
       price: true,
       redeemedAt: true,
+      encryptedQRCode: true, // render this exact payload as a QR image
       hasExpired: true,
       user: { uid: true, name: true, primaryEmail: true },
       ticketTier: { name: true, price: true },
@@ -886,6 +913,105 @@ const { getPartnerTicketsForMoment } = await itm.query({
 });
 ```
 
+#### Displaying a purchased ITM ticket in a web or mobile app
+
+`Ticket.encryptedQRCode` is the exact opaque payload used by ITM scanners. It is
+a string to encode as a QR image, not an image URL. Render it unchanged: do not
+decrypt it, wrap it in JSON, replace it with the ticket UID, or turn it into a
+URL. Your app does not need ITM's QR encryption key.
+
+Keep the SDK and partner token on your Node server. Authenticate the app user
+and resolve their verified ITM account association on that server, then use
+that account's UID (or verified email/phone) in the `user` filter. Do not trust
+an account identifier supplied by the app client: partner tokens grant access
+to the brand's tickets and do not authenticate individual attendees. The token
+only retrieves tickets for its own brand's moments.
+
+For example, install `qrcode` in your server application (`npm install qrcode`,
+plus `npm install -D @types/qrcode` for TypeScript), and generate a PNG data URL:
+
+```typescript
+import QRCode from "qrcode";
+import { createITMPartnerClient } from "@itm-studio/partner-sdk";
+
+const itm = createITMPartnerClient({
+  token: process.env.ITM_PARTNER_TOKEN!,
+});
+
+// Call only after resolving itmUserUid from the authenticated user's verified
+// account association on your server. It must not come from request parameters.
+async function loadMyMomentTickets(
+  itmUserUid: string,
+  momentSlug: string,
+  cursor?: string,
+) {
+  const { getPartnerTicketsForMoment: page } = await itm.query({
+    getPartnerTicketsForMoment: {
+      __args: {
+        momentSlug,
+        user: { userUid: itmUserUid },
+        take: 50,
+        ...(cursor ? { cursor } : {}),
+      },
+      tickets: {
+        uid: true,
+        encryptedQRCode: true,
+        redeemedAt: true,
+        hasExpired: true,
+        ticketTier: { name: true },
+        moment: {
+          name: true,
+          startDate: true,
+          timezone: true,
+          publicVenuePreview: { city: true, country: true, countryCode: true },
+        },
+      },
+      hasNextPage: true,
+      nextCursor: true,
+    },
+  });
+
+  return {
+    tickets: await Promise.all(page.tickets.map(async (ticket) => ({
+      uid: ticket.uid,
+      ticketTierName: ticket.ticketTier.name,
+      moment: ticket.moment,
+      redeemedAt: ticket.redeemedAt,
+      hasExpired: ticket.hasExpired,
+      qrCodeImageUrl: await QRCode.toDataURL(ticket.encryptedQRCode, {
+        errorCorrectionLevel: "H",
+        margin: 4,
+        width: 300,
+      }),
+    }))),
+    hasNextPage: page.hasNextPage,
+    nextCursor: page.nextCursor,
+  };
+}
+```
+
+Return this page only to the authenticated owner, with `Cache-Control: private,
+no-store`. A web app can display `ticket.qrCodeImageUrl` as an image:
+
+```tsx
+<img src={ticket.qrCodeImageUrl} alt="ITM ticket QR code" width={300} height={300} />
+```
+
+A mobile app can display the same PNG data URL using its image component.
+Alternatively, return `encryptedQRCode` only to the authenticated owner and
+pass it unchanged to the app's QR component. Preserve a square image, black
+modules on a white background, and the white margin; avoid cropping or overlays.
+
+Fetch fresh ticket data whenever the ticket screen opens or regains focus.
+Transfers can change the holder and rotate the QR payload, and cancelled or
+refunded tickets no longer appear in this confirmed-ticket query. Avoid shared
+caches and application logs containing ticket payloads or images.
+
+Displaying a QR is separate from admission validation. ITM's scanner checks
+the current ticket and its applicable admission rules at scan time. Display
+`redeemedAt` and `hasExpired` as ticket metadata; they are not a substitute for
+scanner validation, especially for tickets with multiple admissions.
+
 ### `getPartnerCustomersForMoment`
 
 Get paginated customers (users with their tickets) for a moment.
@@ -954,6 +1080,117 @@ pages and optional exact counts can be up to 30 seconds old. Consent and
 suppression fields reflect ITM's current brand-scoped records but do not replace
 your legal-purpose and communications-compliance checks.
 
+### Membership tiers and members
+
+`getPartnerMembershipTiers` and `getPartnerMembers` use your partner token to
+select the brand; neither accepts a brand ID. Both queries use optional `input`
+with `cursor` and `take` (default 50, maximum 100), returning `totalCount`,
+`hasNextPage`, and `nextCursor`. These operations require a partner token;
+adding them to the SDK does not grant access to agent sessions.
+
+#### `getPartnerMembershipTiers`: fetch every tier
+
+Unfiltered results include inactive and private tiers, but exclude soft-deleted
+tiers. Optional filters are `search` (name or slug), `isActive`, `isPublic`, and
+`passTypes`. Tiers are ordered by `sortOrder`, then creation order.
+
+```typescript
+import type { GetPartnerMembershipTiersInput } from "@itm-studio/partner-sdk";
+
+let tierCursor: string | null = null;
+do {
+  const tierInput: GetPartnerMembershipTiersInput = { cursor: tierCursor, take: 100 };
+  const { getPartnerMembershipTiers: page } = await itm.query({
+    getPartnerMembershipTiers: {
+      __args: { input: tierInput },
+      membershipTiers: {
+        uid: true, name: true, slug: true, passType: true,
+        currencyCode: true, price: true, yearlyPrice: true, oneTimePrice: true,
+        isActive: true, isPublic: true, activeMemberCount: true,
+      },
+      totalCount: true, hasNextPage: true, nextCursor: true,
+    },
+  });
+  // Process or persist page.membershipTiers on your server.
+  if (!page.hasNextPage) break;
+  if (!page.nextCursor || page.nextCursor === tierCursor) {
+    throw new Error("Missing or repeated membership tier cursor");
+  }
+  tierCursor = page.nextCursor;
+} while (true);
+```
+
+Tier `price`, `yearlyPrice`, and `oneTimePrice` are stored in hundredths of the
+currency's major unit, including JPY: divide by 100 to display a major-unit
+amount. These are ITM prices, not Stripe minor-unit amounts.
+`activeMemberCount` counts ACTIVE and PAST_DUE membership rows, excluding deleted
+users; it is not a count of distinct people.
+
+#### `getPartnerMembers`: fetch brand-wide or selected tiers
+
+Each `members` row represents one membership, identified by its `uid`, with
+`customer` and `membershipTier` details. A customer may appear more than once;
+use `customer.uid` to group people when needed. It matches the customer UID
+returned by `getPartnerAudience`. Members are ordered newest first.
+
+```typescript
+import type { GetPartnerMembersInput } from "@itm-studio/partner-sdk";
+
+// Leave empty for the entire brand. To select tiers, use:
+// { membershipTierUids: ["tier-uid"] }
+const memberFilters: GetPartnerMembersInput = {};
+let memberCursor: string | null = null;
+do {
+  const memberInput: GetPartnerMembersInput = { ...memberFilters, cursor: memberCursor, take: 100 };
+  const { getPartnerMembers: page } = await itm.query({
+    getPartnerMembers: {
+      __args: { input: memberInput },
+      members: {
+        uid: true, status: true, source: true, membershipNumber: true,
+        quantity: true, purchaseType: true, issuedAt: true,
+        currentPeriodStart: true, currentPeriodEnd: true,
+        cancelAtPeriodEnd: true, remainingUses: true,
+        customer: { uid: true, name: true, email: true, emailVerified: true, phoneNumber: true },
+        membershipTier: { uid: true, name: true, slug: true, passType: true },
+      },
+      totalCount: true, hasNextPage: true, nextCursor: true,
+    },
+  });
+  // Process or persist page.members on your server.
+  if (!page.hasNextPage) break;
+  if (!page.nextCursor || page.nextCursor === memberCursor) {
+    throw new Error("Missing or repeated membership cursor");
+  }
+  memberCursor = page.nextCursor;
+} while (true);
+```
+
+The default includes ACTIVE, PAST_DUE, CANCELLED, EXPIRED, and REFUNDED.
+PENDING represents unpaid checkout reservations and is excluded unless requested
+explicitly. To include every status, set `memberFilters.statuses` to
+`["ACTIVE", "PAST_DUE", "CANCELLED", "EXPIRED", "REFUNDED", "PENDING"]`.
+An empty or null statuses list also uses the default.
+
+Additional filters include `search` (name, email, phone, or exact membership
+number), `sources`, `customerUids`, `cancelAtPeriodEnd`, `createdAtFrom`,
+`createdAtBefore`, `currentPeriodEndFrom`, and `currentPeriodEndBefore`.
+`From` dates are inclusive and `Before` dates exclusive. Keep filters identical
+across pages. Tier and customer UID lists accept at most 100 distinct values;
+search accepts at most 100 characters. Foreign and nonexistent tier UIDs return
+the same error.
+
+Deleted users are excluded. Memberships on soft-deleted tiers remain available,
+so fetch the brand-wide member listing directly rather than assembling it by
+looping over listed tiers. Pagination reads live data without a snapshot
+guarantee: changes during a walk, especially tier reordering, can omit or repeat
+rows. `remainingUses: null` means unlimited; a null `currentPeriodEnd` alone does
+not establish whether a membership has no expiry.
+
+The partner responses expose the allowlisted customer, membership, and tier
+fields, excluding QR tokens, Stripe/payment identifiers, guest information, and
+form responses. Both endpoints are limited to 120 requests per minute per
+partner token.
+
 ### `getPartnerMomentCollection`
 
 Get a moment collection by slug. Collections group related moments together (e.g. a summer series, a festival lineup). Returns the collection with its moments and links.
@@ -1344,6 +1581,75 @@ await itm.mutation({
 });
 ```
 
+### Create a subscribe drop and capture signups without OTP
+
+Use a **partner API token on your server**. First create a drop, then pass its UID
+with each signup. These mutations use the brand associated with the token.
+
+```ts
+const { createPartnerBrandDrop: drop } = await itm.mutation({
+  createPartnerBrandDrop: {
+    __args: {
+      input: {
+        name: 'Join our community',
+        ctaType: 'SUBSCRIBE',
+        coverImageUid: 'your-brand-image-uid',
+        isPublic: true,
+        captureName: true,
+        captureEmail: true,
+        consentText: 'I agree to receive updates from this brand.',
+      },
+    },
+    uid: true,
+    slug: true,
+  },
+});
+
+const { createPartnerBrandSubscription: signup } = await itm.mutation({
+  createPartnerBrandSubscription: {
+    __args: {
+      input: {
+        dropUid: drop.uid,
+        fullName: 'Jane Subscriber',
+        email: 'jane@example.com',
+        phoneNumber: '+14155550123',
+        requireOtpVerification: false, // Also the default when omitted.
+        compliance: {
+          pageUrl: 'https://example.com/join',
+          submissionMethod: 'partner_sdk',
+        },
+      },
+    },
+    verificationRequired: true,
+    subscription: { uid: true, isActive: true },
+  },
+});
+// signup.verificationRequired === false; no OTP or user login step is required.
+```
+
+- `createPartnerBrandDrop` supports `ctaType: 'SUBSCRIBE'`. Upload/register an
+  image with `getPartnerUploadUrl` and `createPartnerMediaAsset`, or select an
+  existing image with `getPartnerMediaAssets`. Both cover images must be active
+  assets owned by this brand. Save the returned drop UID and reuse it for signups;
+  retrying drop creation creates another drop.
+- `dropUid` is optional. Supplying it creates both the brand subscription and the
+  drop attribution, using the existing drop consent, list, and trigger flow.
+  Retrying a signup reuses the subscription and its drop attribution.
+- The drop must belong to the token's brand, be undeleted, and use `SUBSCRIBE`.
+  Required name/email capture still applies. Full names need first and last name;
+  emails are normalized and phones use E.164. Existing drops with required custom
+  checkbox or guest-information fields still enforce those requirements; this
+  simple signup input does not collect those additional fields.
+- Contact detail synchronization runs asynchronously. Account email ownership
+  remains subject to the existing profile verification/conflict rules; it does
+  not block creation of the subscription. Subscription capture does not verify
+  the person's identity.
+- Only submit people who opted in. The drop's configured `consentText` is stored
+  with its attribution. Supply the subscriber's actual compliance metadata when
+  available; otherwise request metadata describes your server.
+- Both mutations require a partner token (agent sessions are not accepted) and
+  are limited to 30 requests per minute. Queue larger imports accordingly.
+
 ### `createPartnerBrandSubscription`
 
 Subscribe a phone number to the authenticated partner brand.
@@ -2021,3 +2327,38 @@ Each requested revision gets a new reservation and brand media asset.
 Deploy the backend reservation migration and schema before publishing SDK 0.3.3,
 then release the Eve and Backstage consumers. These operations do not call an
 image provider or consume notification credits.
+
+
+### Record an off-site contribution
+
+Partner tokens and brand-agent sessions can use `getPartnerContributionPages` to
+choose a page, then log money already received outside ITM. The backend derives
+brand scope from authentication. Name and amount are required; email, phone (with
+country code), and note are optional. This creates no charge, refund capability,
+new account, or automatic receipt. Paused pages accept manual records; archived
+pages reject new records. Amounts use ITM cents (major units × 100, including JPY).
+
+```ts
+const result = await itm.mutation({
+  createPartnerManualContribution: {
+    __args: { input: {
+      contributionPageUid: pageUid,
+      currencyCode: pageCurrencyCode, // Prevent stale page currency from changing the amount.
+      requestUid, // Generate once and retain unchanged across retries.
+      name: 'Alex',
+      amountCents: 2500,
+    } },
+    uid: true,
+    source: true, // OFF_SITE
+    status: true, // SUCCEEDED
+  },
+});
+```
+
+`ContributionAdmin.donorEmail` is nullable for name-only manual entries.
+Set `sendReceipt: true` with an `email` to request a receipt. The backend chooses
+and freezes `manualReceiptType` (`REGULAR` or `DONATION`) from the brand's current
+receipt eligibility. Omit it for no receipt. `userUid` is populated when entered
+email or phone matches a current verified ITM identity; unmatched contacts do not
+create an account, and conflicting matches are rejected. `source` distinguishes
+`STRIPE`, `OFF_SITE`, and in-person `POS` independently of payment status.