@itm-studio/partner-sdk 0.3.4 → 0.3.6

package/README.md

@@ -515,6 +515,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.