@itm-studio/partner-sdk 0.3.5 → 0.3.7

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,
@@ -515,6 +520,114 @@ 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.
 
+### `getPartnerContributionPages`
+
+Get paginated contribution (tip/donation) pages for the brand associated with
+your partner token, newest first. Each page carries its hosted checkout URL
+(`publicUrl`) and confirmed-money totals, so a partner site can link straight
+to checkout and show progress without computing anything itself.
+
+Like every contribution operation, this query is guarded for the brand partner
+token (`BrandPartnerGuard`): call it from a `token` client. Brand Agent
+`agentSession` and `agentAccess` clients are not authorized for it and fail
+closed, and the brand is always derived from the token — never pass a brand ID.
+
+Supported filters:
+
+- `status`: `ACCEPTING`, `PAUSED`, or `ARCHIVED`; omit for all pages.
+- `search`: case-insensitive match over title and slug.
+- `cursor` and `take` (1–100, default 25): use `nextCursor` while `hasNextPage` is true.
+
+```typescript
+const { getPartnerContributionPages } = await itm.query({
+  getPartnerContributionPages: {
+    __args: { status: "ACCEPTING", take: 20 },
+    items: {
+      uid: true,
+      slug: true,
+      title: true,
+      description: true,
+      publicUrl: true, // hosted checkout page on ITM
+      qrCodeImageUrl: true, // data URL that resolves to publicUrl
+      canContribute: true,
+      currency: { code: true, symbol: true },
+      suggestedAmountsCents: true,
+      recommendedAmountCents: true,
+      successfulContributionCount: true,
+      grossAmountCents: true,
+      netAmountCents: true,
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+`grossAmountCents`, `refundedAmountCents`, and `netAmountCents` are strings
+because totals can exceed a GraphQL `Int`. `canContribute` is `false` while a
+page is paused, archived, or its payout account is not verified; render the
+link only when it is `true`.
+
+### `getPartnerContributions`
+
+Get paginated contributions for the brand associated with your partner token,
+newest first. This is the feed for a live contributor wall or rolling counter:
+filter `status: "SUCCEEDED"` to list only confirmed contributors, and read
+`note` for the optional message they left at checkout.
+
+This query runs behind the same brand partner guard as
+`getPartnerContributionPages`, so it requires a `token` client; Brand Agent
+`agentSession` and `agentAccess` credentials are rejected. It is the
+partner-facing feed only — brand-admin contribution and refund administration
+operations are not part of the partner surface.
+
+Supported filters:
+
+- `contributionPageUid`: restrict to one page owned by the brand (a page from
+  another brand returns a `Contribution page not found` error).
+- `status`: `SUCCEEDED`, `PENDING`, `PROCESSING`, `REVIEW_REQUIRED`, `FAILED`,
+  or `EXPIRED`; omit for all statuses. Only `SUCCEEDED` is confirmed money.
+- `search`: case-insensitive match over donor name and email.
+- `cursor` and `take` (1–100, default 25): use `nextCursor` while `hasNextPage` is true.
+
+```typescript
+const { getPartnerContributions } = await itm.query({
+  getPartnerContributions: {
+    __args: {
+      contributionPageUid: page.uid,
+      status: "SUCCEEDED",
+      take: 50,
+      cursor: nextCursor,
+    },
+    items: {
+      uid: true,
+      donorName: true,
+      note: true, // null when the contributor left no note
+      amountCents: true,
+      currencyCode: true,
+      paidAt: true,
+      createdAt: true,
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+
+// Rolling feed: items arrive newest first; totalCount is the number of
+// matching contributions (not distinct donors) for the filter.
+```
+
+Refunds do not change `status`: a fully refunded contribution stays
+`SUCCEEDED` with `refundedAmountCents` equal to `amountCents`. For a public
+wall or counter, also skip rows where `refundedAmountCents >= amountCents`.
+`donorName` and `note` are unmoderated contributor input; escape them and apply
+your own moderation before rendering publicly. `donorEmail` is available for
+reconciliation but is personal data; do not render it on public surfaces.
+Amounts are ITM cents (major units × 100, also for zero-decimal currencies) —
+see [Money Amounts](#money-amounts).
+
 ### `getPartnerMoment`
 
 Get a single moment by slug.
@@ -539,6 +652,11 @@ const { getPartnerMoment } = await itm.query({
       city: true,
       postalCode: true,
     },
+    publicVenuePreview: {
+      city: true,
+      country: true,
+      countryCode: true,
+    },
     ticketTiers: {
       name: true,
       price: true,
@@ -548,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`.
@@ -752,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,
     },
@@ -766,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 },
@@ -778,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.
@@ -846,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.
@@ -1913,3 +2258,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.