@itm-studio/partner-sdk 0.1.0

package/README.md

@@ -0,0 +1,259 @@
+# @itm-studio/partner-sdk
+
+Type-safe TypeScript SDK for the ITM Partner API. Built with [genql](https://genql.dev/) — full autocomplete, zero introspection required.
+
+[![CI](https://github.com/itm-studio/itm-partner-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/itm-studio/itm-partner-sdk/actions/workflows/ci.yml)
+[![Schema Registry](https://img.shields.io/badge/schema-GraphQL%20Hive-blue)](https://app.graphql-hive.com/itm/itm-partner-api/production)
+
+## Install
+
+```bash
+npm install @itm-studio/partner-sdk
+```
+
+## Quick Start
+
+```typescript
+import { createITMPartnerClient } from '@itm-studio/partner-sdk';
+
+const itm = createITMPartnerClient({
+  token: process.env.ITM_PARTNER_TOKEN!,
+});
+
+// Get all upcoming moments for your brand
+const { getPartnerMomentsForBrand } = await itm.query({
+  getPartnerMomentsForBrand: {
+    __args: { status: 'UPCOMING', take: 10 },
+    moments: {
+      uid: true,
+      name: true,
+      slug: true,
+      startDate: true,
+      endDate: true,
+      status: true,
+      venue: {
+        name: true,
+        city: true,
+        country: true,
+      },
+      ticketTiers: {
+        name: true,
+        price: true,
+        currency: { code: true, symbol: true },
+        remainingSupply: true,
+      },
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+## Authentication
+
+Get your partner API token from the ITM backstage dashboard: **Settings > Partner API**.
+
+The token is sent as the `x-partner-api-key` header on every request. Your brand is determined automatically from the token — no need to pass brand IDs.
+
+## Available Queries
+
+### `getPartnerMomentsForBrand`
+
+Get paginated moments (events) for your brand.
+
+```typescript
+const { getPartnerMomentsForBrand } = await itm.query({
+  getPartnerMomentsForBrand: {
+    __args: {
+      take: 20,             // items per page (default: 50)
+      cursor: nextCursor,   // from previous response
+      status: 'UPCOMING',   // UPCOMING | LIVE | ENDED
+      sortOrder: 'ASC',     // ASC | DESC (by start date)
+    },
+    moments: { uid: true, name: true, startDate: true },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+### `getPartnerMoment`
+
+Get a single moment by slug.
+
+```typescript
+const { getPartnerMoment } = await itm.query({
+  getPartnerMoment: {
+    __args: { slug: 'my-event-slug' },
+    uid: true,
+    name: true,
+    startDate: true,
+    endDate: true,
+    ticketTiers: {
+      name: true,
+      price: true,
+      numSold: true,
+      remainingSupply: true,
+    },
+  },
+});
+```
+
+### `getPartnerTicketsForMoment`
+
+Get paginated tickets for a moment.
+
+```typescript
+const { getPartnerTicketsForMoment } = await itm.query({
+  getPartnerTicketsForMoment: {
+    __args: {
+      momentSlug: 'my-event-slug',
+      checkedIn: true,  // optional: filter by check-in status
+      take: 50,
+    },
+    tickets: {
+      uid: true,
+      price: true,
+      redeemedAt: true,
+      hasExpired: true,
+      user: { uid: true, name: true, primaryEmail: true },
+      ticketTier: { name: true, price: true },
+      payment: { amount: true, status: true },
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+### `getPartnerCustomersForMoment`
+
+Get paginated customers (users with their tickets) for a moment.
+
+```typescript
+const { getPartnerCustomersForMoment } = await itm.query({
+  getPartnerCustomersForMoment: {
+    __args: { momentSlug: 'my-event-slug', take: 50 },
+    customers: {
+      user: { uid: true, name: true, primaryEmail: true, phoneNumber: true },
+      tickets: { uid: true, price: true, redeemedAt: true },
+    },
+    totalCount: true,
+    hasNextPage: true,
+    nextCursor: true,
+  },
+});
+```
+
+## Pagination
+
+All list endpoints use cursor-based pagination:
+
+```typescript
+let cursor: string | null = null;
+
+do {
+  const { getPartnerTicketsForMoment } = await itm.query({
+    getPartnerTicketsForMoment: {
+      __args: { momentSlug: 'my-event', cursor, take: 50 },
+      tickets: { uid: true, user: { name: true } },
+      hasNextPage: true,
+      nextCursor: true,
+      totalCount: true,
+    },
+  });
+
+  for (const ticket of getPartnerTicketsForMoment.tickets) {
+    console.log(ticket.user.name);
+  }
+
+  cursor = getPartnerTicketsForMoment.nextCursor ?? null;
+} while (cursor);
+```
+
+## Custom Base URL
+
+For staging or local development:
+
+```typescript
+const itm = createITMPartnerClient({
+  token: process.env.ITM_PARTNER_TOKEN!,
+  baseUrl: 'https://staging-api.itm.studio/graphql',
+});
+```
+
+## Development
+
+```bash
+npm install
+npm run generate   # Generate typed client from schema
+npm test           # Run tests
+npm run build      # Build for publishing
+```
+
+## Architecture
+
+```
+itm-backend (NestJS)                    itm-partner-sdk
+┌─────────────────────┐                ┌────────────────────────┐
+│ Full GraphQL Schema  │                │ schema/partner.graphql │
+│ (8000+ lines)        │  ── export ──▶ │ (partner subset only)  │
+│                      │                │                        │
+│ BrandPartnerGuard    │                │        genql           │
+│ x-partner-api-key    │                │          │             │
+│ Authorization Bearer │                │          ▼             │
+└─────────────────────┘                │ src/generated/ (typed) │
+         ▲                              │          │             │
+         │                              │          ▼             │
+         │    x-partner-api-key         │ createITMPartnerClient │
+         └──────────────────────────────│                        │
+                                        └────────────────────────┘
+                                                   │
+                                                   ▼
+                                        ┌────────────────────────┐
+                                        │   GraphQL Hive          │
+                                        │   Schema Registry       │
+                                        │   Breaking change guard │
+                                        └────────────────────────┘
+```
+
+- **Partner schema** is a curated subset of the full backend schema — only partner-safe endpoints
+- **genql** generates a fully typed client from the schema at build time — no runtime introspection
+- **GraphQL Hive** validates schema changes on every PR and blocks breaking changes
+- **Authentication** uses the existing `BrandPartnerGuard` — token sent via `x-partner-api-key` header
+
+## Schema Governance (Hive)
+
+This SDK uses [GraphQL Hive](https://the-guild.dev/graphql/hive) for schema governance.
+
+- **On PRs**: `schema:check` runs automatically to detect breaking changes before merge
+- **On push to main**: `schema:publish` updates the registry so the schema history is tracked
+- **Dashboard**: [app.graphql-hive.com/itm/itm-partner-api/production](https://app.graphql-hive.com/itm/itm-partner-api/production)
+
+```bash
+# Local usage (requires HIVE_TOKEN env var)
+npm run schema:check    # Check for breaking changes
+npm run schema:publish  # Publish schema to registry
+```
+
+## CI/CD
+
+| Job | Trigger | What it does |
+|---|---|---|
+| `build-and-test` | Every push & PR | Install, generate, lint, test, build |
+| `schema-check` | PRs only | Validates schema changes won't break partners |
+| `schema-publish` | Push to main | Publishes schema to Hive registry |
+| `publish` | Push to main | Auto-bumps patch version and publishes to NPM |
+
+## Adding New Partner Endpoints
+
+When exposing a new backend endpoint to partners:
+
+1. Add the query/mutation to `schema/partner.graphql` with only the fields partners should access
+2. Run `npm run generate` to regenerate the typed client
+3. Add tests in `tests/queries.test.ts`
+4. Open a PR — Hive will validate the schema change isn't breaking
+5. After merge, the schema is auto-published to Hive and a new SDK version can be released