@itm-studio/partner-sdk 0.3.5 → 0.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itm-studio/partner-sdk",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "TypeScript SDK for the ITM Partner API — typed GraphQL client with zero introspection required",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -49,8 +49,13 @@
   "devDependencies": {
     "@genql/cli": "^6.3.3",
     "@graphql-hive/cli": "^0.46.0",
+    "@types/pngjs": "^6.0.5",
+    "@types/qrcode": "^1.5.6",
     "esbuild": "0.27.3",
+    "jsqr": "^1.4.0",
     "msw": "^2.7.0",
+    "pngjs": "^7.0.0",
+    "qrcode": "^1.5.4",
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",
     "vite": "^6.0.0",

package/schema/partner.graphql

@@ -438,6 +438,21 @@ enum TagSource {
   AUTO
 }
 
+enum ContributionStatus {
+  EXPIRED
+  FAILED
+  PENDING
+  PROCESSING
+  REVIEW_REQUIRED
+  SUCCEEDED
+}
+
+enum ContributionPageStatusFilter {
+  ACCEPTING
+  ARCHIVED
+  PAUSED
+}
+
 # ─── Types ───────────────────────────────────────────────────────────────────
 
 type Currency {
@@ -451,6 +466,102 @@ type Currency {
   updatedAt: DateTime!
 }
 
+"""
+A contribution (tip/donation) page owned by the partner's brand, with confirmed
+money totals. Amount fields are ITM cents (major units × 100, including
+zero-decimal currencies). Totals are strings because they can exceed Int.
+"""
+type ContributionPageAdmin {
+  uid: ID!
+  slug: String!
+  title: String!
+  description: String
+  """Legal/terms copy rendered beneath the page."""
+  finePrint: String
+  brandUid: String!
+  brandName: String!
+  brandSlug: String!
+  currency: Currency!
+  suggestedAmountsCents: [Int!]!
+  """Highlighted quick-pick; always one of suggestedAmountsCents."""
+  recommendedAmountCents: Int
+  minimumAmountCents: Int
+  maximumAmountCents: Int
+  requireItmAccount: Boolean!
+  """Shows an optional note field at checkout."""
+  allowContributorNote: Boolean!
+  isAccepting: Boolean!
+  """True when the page is accepting, not archived, and its payout account is verified."""
+  canContribute: Boolean!
+  """Public checkout URL for this page on ITM."""
+  publicUrl: String!
+  """Data URL of a QR code that resolves to publicUrl."""
+  qrCodeImageUrl: String!
+  archivedAt: DateTime
+  successfulContributionCount: Int!
+  """Number of successful refunds."""
+  refundCount: Int!
+  grossAmountCents: String!
+  refundedAmountCents: String!
+  """Brand net after platform and processing fees, reduced pro rata by successful refunds."""
+  netAmountCents: String!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+enum ContributionSource {
+  STRIPE
+  OFF_SITE
+  POS
+}
+
+enum ManualContributionReceiptType {
+  REGULAR
+  DONATION
+}
+
+input CreateManualContributionInput {
+  sendReceipt: Boolean
+  currencyCode: String!
+  contributionPageUid: String!
+  amountCents: Int!
+  requestUid: String!
+  name: String!
+  email: String
+  phoneNumber: String
+  note: String
+}
+
+"""
+A single contribution to one of the brand's contribution pages.
+Only SUCCEEDED contributions represent confirmed money.
+"""
+type ContributionAdmin {
+  uid: ID!
+  contributionPageUid: String!
+  """Page title snapshotted at checkout."""
+  pageTitle: String!
+  donorName: String!
+  donorEmail: String
+  donorPhoneNumber: String
+  source: ContributionSource!
+  userUid: String
+  manualReceiptType: ManualContributionReceiptType
+  """Note left by the contributor at checkout; null when none was given."""
+  note: String
+  currencyCode: String!
+  amountCents: Int!
+  refundedAmountCents: Int!
+  status: ContributionStatus!
+  paidAt: DateTime
+  """Paid without an ITM account."""
+  isGuest: Boolean!
+  """When a guest contribution was linked to an ITM account."""
+  claimedAt: DateTime
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
 """
 The authenticated partner's brand identity and public-facing details.
 The brand is derived from the partner token and cannot be selected by UID or slug.
@@ -480,6 +591,18 @@ type Venue {
   updatedAt: DateTime!
 }
 
+"""
+Public location text for a moment, without the venue name or street address.
+Available even when the full venue is hidden until RSVP.
+"""
+type MomentPublicVenuePreview {
+  city: String!
+  """Display country label; use countryCode when an ISO country code is needed."""
+  country: String!
+  """ISO country code when available."""
+  countryCode: String
+}
+
 """
 A slim projection of the cover image media asset.
 Only the publicly useful fields (URL and MIME type) are exposed.
@@ -540,7 +663,10 @@ type Moment {
   lineupDisplayLabel: MomentLineupDisplayLabel!
   """Cover image for the moment. Null if no cover image is set."""
   coverImage: MomentCoverImage!
+  """Full venue details. Null when no venue is set or the caller cannot reveal it."""
   venue: Venue
+  """Public city/country location text. Null when no venue is set."""
+  publicVenuePreview: MomentPublicVenuePreview
   """Public tag assignments owned by the authenticated partner's brand."""
   momentTags(
     pagination: PaginationInput
@@ -602,6 +728,13 @@ type Ticket {
   uid: ID!
   price: Float!
   redeemedAt: DateTime
+  """
+  Opaque ticket payload to encode unchanged as a QR image for ITM scanners.
+  This is not an image URL. No decryption key is needed to render it.
+  Fetch on a trusted server, verify the app user's current ticket ownership,
+  and refetch before display because transfers can rotate the payload.
+  Rendering a QR does not establish admission eligibility; ITM validates it at scan time.
+  """
   encryptedQRCode: String!
   notes: String
   externalId: String
@@ -735,6 +868,17 @@ enum EventImportPlatform {
   EVENTBRITE
 }
 
+"""
+Match the current ITM ticket owner by exactly one of userUid, email, or phoneNumber.
+For an attendee app, derive this identifier from the authenticated user's verified
+ITM account association on your server; a caller-supplied identifier is not proof of ownership.
+"""
+input PartnerTicketUserLookupInput {
+  userUid: String
+  email: String
+  phoneNumber: String
+}
+
 input PartnerMomentAttendanceLookupInput {
   """
   ITM moment UID. Provide exactly one of momentUid, momentSlug, or externalPlatform with externalId.
@@ -883,6 +1027,20 @@ type GetPartnerDropsResponse {
   nextCursor: String
 }
 
+type ContributionPagesResponse {
+  items: [ContributionPageAdmin!]!
+  totalCount: Int!
+  hasNextPage: Boolean!
+  nextCursor: String
+}
+
+type ContributionsResponse {
+  items: [ContributionAdmin!]!
+  totalCount: Int!
+  hasNextPage: Boolean!
+  nextCursor: String
+}
+
 type GetMomentLineupsResponse {
   lineups: [MomentLineup!]!
   totalCount: Int!
@@ -1262,7 +1420,185 @@ type AgentMediaUploadReservation {
   mediaAsset: MediaAsset
 }
 
+enum MembershipBillingInterval {
+  MONTHLY
+  MONTHLY_OR_YEARLY
+  YEARLY
+}
+
+enum MembershipExpiryType {
+  FIXED_DATE
+  NO_EXPIRY
+  ROLLING
+}
+
+enum MembershipPassType {
+  ONE_TIME
+  RECURRING
+  RECURRING_OR_ONE_TIME
+}
+
+enum MembershipPurchaseType {
+  ONE_TIME
+  RECURRING
+}
+
+enum MembershipSource {
+  ADMIN_GRANT
+  IMPORT
+  PURCHASE
+}
+
+enum MembershipStatus {
+  ACTIVE
+  CANCELLED
+  EXPIRED
+  PAST_DUE
+  PENDING
+  REFUNDED
+}
+
+input GetPartnerMembersInput {
+  """Only memberships set (or not set) to cancel at period end"""
+  cancelAtPeriodEnd: Boolean
+  """Membership created strictly before this instant"""
+  createdAtBefore: DateTime
+  """Membership created at or after this instant"""
+  createdAtFrom: DateTime
+  """Current period ends strictly before this instant (e.g. expiring soon)"""
+  currentPeriodEndBefore: DateTime
+  """Current period ends at or after this instant"""
+  currentPeriodEndFrom: DateTime
+  """Cursor UID returned as nextCursor by the previous page"""
+  cursor: String
+  """
+  Restrict to these customer UIDs (PartnerMemberCustomer.uid, same as getPartnerAudience customer uid)
+  """
+  customerUids: [String!]
+  """Restrict to these membership tier UIDs (must belong to the brand)"""
+  membershipTierUids: [String!]
+  """
+  Case-insensitive search over member name, email, phone number, or exact membership number
+  """
+  search: String
+  sources: [MembershipSource!]
+  """
+  Membership statuses to include. Omit for every status except PENDING (unpaid checkout reservations).
+  """
+  statuses: [MembershipStatus!]
+  """Page size. Defaults to 50, maximum 100."""
+  take: Int
+}
+
+type GetPartnerMembersResponse {
+  hasNextPage: Boolean!
+  members: [PartnerMember!]!
+  nextCursor: String
+  totalCount: Int!
+}
+
+input GetPartnerMembershipTiersInput {
+  """Cursor UID returned as nextCursor by the previous page"""
+  cursor: String
+  isActive: Boolean
+  isPublic: Boolean
+  passTypes: [MembershipPassType!]
+  """Case-insensitive search over tier name and slug"""
+  search: String
+  """Page size. Defaults to 50, maximum 100."""
+  take: Int
+}
+
+type GetPartnerMembershipTiersResponse {
+  hasNextPage: Boolean!
+  membershipTiers: [PartnerMembershipTier!]!
+  nextCursor: String
+  totalCount: Int!
+}
+
+type PartnerMember {
+  billingInterval: MembershipBillingInterval
+  cancelAtPeriodEnd: Boolean!
+  cancelledAt: DateTime
+  createdAt: DateTime!
+  currentPeriodEnd: DateTime
+  currentPeriodStart: DateTime
+  customer: PartnerMemberCustomer!
+  """First issuance time; falls back to createdAt for legacy rows"""
+  issuedAt: DateTime!
+  membershipNumber: Int
+  membershipTier: PartnerMemberTier!
+  purchaseType: MembershipPurchaseType
+  quantity: Int!
+  refundedAt: DateTime
+  """Uses the member can redeem now; null means unlimited"""
+  remainingUses: Int
+  source: MembershipSource!
+  status: MembershipStatus!
+  uid: ID!
+  updatedAt: DateTime!
+}
+
+type PartnerMemberCustomer {
+  email: String
+  emailVerified: Boolean!
+  name: String
+  phoneNumber: String
+  uid: String!
+}
+
+type PartnerMemberTier {
+  name: String!
+  passType: MembershipPassType!
+  slug: String!
+  uid: String!
+}
+
+type PartnerMembershipTier {
+  """Memberships currently ACTIVE or PAST_DUE on this tier"""
+  activeMemberCount: Int!
+  benefits: [String!]!
+  billingInterval: MembershipBillingInterval
+  createdAt: DateTime!
+  """ISO 4217 currency code"""
+  currencyCode: String!
+  description: String
+  durationDays: Int
+  expiryType: MembershipExpiryType
+  fixedEndDate: DateTime
+  isActive: Boolean!
+  isPublic: Boolean!
+  memberLimit: Int
+  name: String!
+  """
+  Amount in hundredths of the currency's major unit (always x100, including zero-decimal currencies such as JPY)
+  """
+  oneTimePrice: Int
+  passType: MembershipPassType!
+  """
+  Amount in hundredths of the currency's major unit (always x100, including zero-decimal currencies such as JPY)
+  """
+  price: Int!
+  slug: String!
+  sortOrder: Int!
+  supplyCap: Int
+  totalUses: Int
+  trialDays: Int!
+  uid: ID!
+  updatedAt: DateTime!
+  """
+  Amount in hundredths of the currency's major unit (always x100, including zero-decimal currencies such as JPY)
+  """
+  yearlyPrice: Int
+}
+
 type Query {
+  """List the authenticated partner brand's membership rows; PENDING is excluded by default."""
+  getPartnerMembers(input: GetPartnerMembersInput): GetPartnerMembersResponse!
+
+  """List the authenticated partner brand's non-deleted membership tiers, including inactive and private tiers."""
+  getPartnerMembershipTiers(input: GetPartnerMembershipTiersInput): GetPartnerMembershipTiersResponse!
+
   """Get the authenticated agent operator email for the approval preview. Requires a brand-agent session with SEND_EMAIL; unavailable to partner API keys."""
   getPartnerAgentEmailContext: BrandAgentEmailContext!
   getAgentMediaUpload(uid: String!): AgentMediaUploadReservation!
@@ -1335,15 +1671,21 @@ type Query {
   ): PartnerMomentAttendanceStats
 
   """
-  Get paginated tickets for a moment.
+  Get confirmed tickets for a moment owned by the partner token's brand.
+  Use the user filter when retrieving an attendee's tickets for QR display.
+  The partner token authorizes brand access, not the app user's identity.
+  Follow hasNextPage/nextCursor to retrieve every ticket.
   """
   getPartnerTicketsForMoment(
     momentSlug: String!
     """Cursor UID for pagination"""
     cursor: String
+    """Page size. Defaults to 50; maximum 100."""
     take: Int
     """Filter by check-in status"""
     checkedIn: Boolean
+    """Match the current ticket owner by exactly one of userUid, email, or phoneNumber."""
+    user: PartnerTicketUserLookupInput
   ): GetTicketsResponse!
 
   """
@@ -1382,6 +1724,36 @@ type Query {
     take: Int
   ): GetBrandEchoesForUserResponse!
 
+  """
+  Paginated contribution pages for the brand associated with the partner token,
+  newest first. Each page carries its public checkout URL and confirmed totals.
+  """
+  getPartnerContributionPages(
+    """ACCEPTING, PAUSED or ARCHIVED; omit for all pages."""
+    status: ContributionPageStatusFilter
+    """Case-insensitive search over title and slug."""
+    search: String
+    cursor: String
+    """1–100, default 25."""
+    take: Int
+  ): ContributionPagesResponse!
+
+  """
+  Paginated contributions for the brand associated with the partner token,
+  newest first. Filter status: SUCCEEDED for confirmed contributors.
+  """
+  getPartnerContributions(
+    """Restrict to one contribution page owned by the brand."""
+    contributionPageUid: String
+    """Omit for all statuses; SUCCEEDED lists paid contributions."""
+    status: ContributionStatus
+    """Case-insensitive search over donor name and email."""
+    search: String
+    cursor: String
+    """1–100, default 25."""
+    take: Int
+  ): ContributionsResponse!
+
   """
   Get paginated ticket tiers for a partner-owned moment.
   Provide either momentSlug or momentUid. Omitted isActive defaults to active tiers only.
@@ -1764,6 +2136,9 @@ type CreatePartnerBrandSubscriptionResponse {
 # ─── Mutations ────────────────────────────────────────────────────────────────
 
 type Mutation {
+  """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(input: CreateManualContributionInput!): ContributionAdmin!
+
   reserveAgentMediaUpload(input: ReserveAgentMediaUploadInput!): AgentMediaUploadReservation!
   finishAgentMediaUpload(uid: String!): Boolean!