vairified 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,538 +1,782 @@
 /**
- * Vairified SDK Types
+ * HTTP transport — internal. Not part of the public API.
  *
+ * The transport is a thin wrapper around native `fetch` that:
+ *
+ * - Injects the API key header on every request.
+ * - Serializes query params (dropping `undefined`) and JSON bodies.
+ * - Applies a request timeout via `AbortController`.
+ * - Maps non-2xx responses to the right typed exception.
+ *
+ * @internal
  * @module
  */
 /**
- * Options for initializing the Vairified client.
+ * Values accepted as query parameters.
+ *
+ * `null` and `undefined` are silently dropped. Arrays are joined with
+ * `','`. Everything else is stringified.
+ *
+ * @internal
+ */
+type QueryParams = Readonly<Record<string, string | number | boolean | readonly (string | number)[] | null | undefined>>;
+/**
+ * Options passed to the internal HTTP layer.
+ *
+ * @internal
+ */
+interface RequestOptions {
+    readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    readonly path: string;
+    readonly query?: QueryParams;
+    readonly body?: unknown;
+}
+/**
+ * Transport configuration.
+ *
+ * @internal
+ */
+interface TransportConfig {
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly timeoutMs: number;
+    readonly fetch: typeof fetch;
+}
+/**
+ * Internal HTTP client. Holds no state between requests — each call
+ * builds a fresh `Request`, runs it, and returns the parsed body.
  *
- * @category Types
+ * @internal
+ */
+declare class HttpTransport {
+    #private;
+    constructor(config: TransportConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+}
+
+/**
+ * Vairified SDK — Partner API v1 wire types.
+ *
+ * These are the raw shapes the server returns or accepts. Request
+ * types (e.g. {@link MatchBatch}, {@link SearchFilters}) are used as-is
+ * by the SDK. Response types (e.g. {@link PartnerMemberWire}) are
+ * wrapped in class instances by the SDK — see the `models/` folder.
+ *
+ * @module
+ */
+/**
+ * Environment preset for the Vairified API.
+ *
+ * @category Client
+ */
+type VairifiedEnvironment = 'production' | 'staging' | 'local';
+/**
+ * Options passed to the {@link Vairified} constructor.
+ *
+ * @category Client
  */
 interface VairifiedOptions {
-    /** API key for authentication */
+    /** Partner API key (`vair_pk_...`). Falls back to `VAIRIFIED_API_KEY`. */
     apiKey?: string;
-    /** Environment preset: "production" (default), "staging", "local" */
-    env?: 'production' | 'staging' | 'local';
-    /** Override API base URL. Takes precedence over env. */
+    /** Environment preset. Falls back to `VAIRIFIED_ENV` or `'production'`. */
+    env?: VairifiedEnvironment;
+    /** Explicit base URL. Takes precedence over `env`. */
     baseUrl?: string;
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
+    /** Request timeout in milliseconds. Defaults to 30_000 (30s). */
+    timeoutMs?: number;
+    /**
+     * Inject a custom `fetch` implementation. Defaults to the global
+     * `fetch`. Useful for test shims or non-Node environments.
+     */
+    fetch?: typeof fetch;
 }
 /**
- * A single rating split with metadata.
+ * Normalized gender tokens emitted by the Partner API.
  *
- * @category Types
+ * @category Members
  */
-interface RatingSplitData {
-    /** The rating value (may be string from API) */
-    rating: string | number;
-    /** Abbreviation (e.g., "VG", "50+") */
-    abbr: string;
-    /** Date of last match in this category */
-    date_played?: string;
+type Gender = 'MALE' | 'FEMALE' | 'OTHER' | 'UNKNOWN';
+/**
+ * Raw rating split — one slice of a player's rating for a specific
+ * category × age bracket.
+ *
+ * @category Members
+ */
+interface RatingSplitWire {
+    readonly rating: number;
+    readonly abbr: string;
 }
 /**
- * Rating splits from API - map of category to rating data.
+ * Raw sport rating — a player's ratings for one sport.
  *
- * @category Types
+ * @category Members
  */
-type RatingSplitsData = Record<string, RatingSplitData | number>;
+interface SportRatingWire {
+    readonly rating: number;
+    readonly abbr: string;
+    readonly ratingSplits: Readonly<Record<string, RatingSplitWire>>;
+}
 /**
- * Player data from getMember endpoint (requires OAuth connection).
+ * Grouped member status flags.
  *
- * @category Types
+ * @category Members
  */
-interface MemberData {
-    /** External player ID (vair_mem_xxx format) */
-    id: string;
-    firstName?: string;
-    lastName?: string;
-    /** Email (only if profile:email scope granted) */
-    email?: string;
-    rating?: number;
-    isVairified?: boolean;
-    ratingSplits?: RatingSplitsData;
-    city?: string;
-    state?: string;
-    country?: string;
-    /** Scopes the player granted to your app */
-    grantedScopes?: string[];
+interface MemberStatusWire {
+    readonly isVairified: boolean;
+    readonly isWheelchair: boolean;
+    readonly isAmbassador: boolean;
+    readonly isRater: boolean;
+    readonly isConnected: boolean;
 }
 /**
- * Player data from search endpoint (public, limited data).
+ * Raw partner-facing member record returned by the Partner API.
  *
- * @category Types
+ * @category Members
  */
-interface PlayerSearchData {
-    /** External player ID (vair_mem_xxx format) */
-    id: string;
-    /** Display name (First Name + Last Initial for privacy) */
-    displayName: string;
-    city?: string;
-    state?: string;
-    country?: string;
-    rating?: number;
-    isVairified?: boolean;
-    /** Whether player has connected to your app */
-    isConnected?: boolean;
+interface PartnerMemberWire {
+    readonly memberId: number;
+    readonly id?: string;
+    readonly firstName: string;
+    readonly lastName: string;
+    readonly fullName: string;
+    readonly displayName: string;
+    readonly age?: number;
+    readonly city?: string;
+    readonly state?: string;
+    readonly zip?: string;
+    readonly country?: string;
+    readonly gender?: Gender;
+    readonly status: MemberStatusWire;
+    readonly sport?: Readonly<Record<string, SportRatingWire>>;
+    readonly activeLeagues?: readonly string[];
+    readonly email?: string;
+    readonly grantedScopes?: readonly string[];
 }
 /**
- * Filters for player search.
+ * Raw rating change notification.
  *
- * @category Types
+ * @category Members
+ */
+interface PartnerRatingUpdateWire {
+    readonly memberId: number;
+    readonly id?: string;
+    readonly displayName?: string;
+    readonly sport?: string;
+    readonly previousRating?: number;
+    readonly newRating?: number;
+    readonly changedAt?: string;
+    readonly ratingSplits?: Readonly<Record<string, RatingSplitWire>>;
+}
+/**
+ * Filters accepted by {@link MembersResource.search}.
+ *
+ * Most callers pass these as keyword arguments directly to `search()`;
+ * the SDK serializes them to query parameters for you.
+ *
+ * @category Members
  */
 interface SearchFilters {
-    /** Name search (partial match) */
+    /** Sport code (e.g. `'pickleball'`) or list of codes. */
+    sport?: string | readonly string[];
+    /** Partial name match (first or last). */
     name?: string;
-    /** City filter */
+    /** Exact numeric member ID. */
+    memberId?: number | string;
     city?: string;
-    /** State code (e.g., "TX") */
     state?: string;
-    /** Country code (e.g., "US") */
     country?: string;
-    /** ZIP/postal code */
-    zipCode?: string;
-    /** Minimum rating (2.0-8.0) */
+    zip?: string;
+    location?: string;
+    gender?: Gender | Lowercase<Gender>;
+    /** When `true`, only return verified players. */
+    vairifiedOnly?: boolean;
+    /** When `true`, only return wheelchair players. */
+    wheelchair?: boolean;
+    /** Lower rating bound (2.0–8.0). */
     ratingMin?: number;
-    /** Maximum rating (2.0-8.0) */
+    /** Upper rating bound (2.0–8.0). */
     ratingMax?: number;
-    /** Gender filter */
-    gender?: 'MALE' | 'FEMALE';
-    /** Only verified players */
-    vairifiedOnly?: boolean;
-    /** Exact age */
+    /** Exact age. */
     age?: number;
-    /** Minimum age */
+    /** Lower age bound. */
     ageMin?: number;
-    /** Maximum age */
+    /** Upper age bound. */
     ageMax?: number;
-    /** Field to sort by */
     sortBy?: string;
-    /** Sort direction */
     sortOrder?: 'asc' | 'desc';
-    /** Page number (1-indexed) */
-    page?: number;
-    /** Results per page (max 100) */
-    limit?: number;
+    /** Page size requested per HTTP request (server cap 100). Default 20. */
+    pageSize?: number;
+    /**
+     * Maximum total results to iterate. When set, the async iterator
+     * stops after yielding this many items, regardless of page count.
+     */
+    maxResults?: number;
 }
 /**
- * Match input for creating a Match.
+ * One scored game within a {@link MatchInput}.
  *
- * @category Types
+ * `scores` contains one integer per team, in the same order as the
+ * parent match's `teams` list. For a standard 2-team game that's
+ * `[team1Score, team2Score]`. Longer lists are supported for
+ * n-team matches.
+ *
+ * All other fields override the parent match's defaults for this
+ * specific game (e.g. a championship game played to 15 when the rest
+ * of the match was to 11).
+ *
+ * @category Matches
+ */
+interface GameInput {
+    readonly scores: readonly number[];
+    readonly identifier?: string;
+    readonly winScore?: number;
+    readonly winBy?: number;
+}
+/**
+ * One match to submit in a {@link MatchBatch}.
+ *
+ * A match is n-team × n-game:
+ *
+ * - `teams: [['p1', 'p2'], ['p3', 'p4']]` — standard doubles
+ * - `teams: [['p1'], ['p2']]` — singles
+ * - `teams: [['p1'], ['p2'], ['p3']]` — 3-way round robin
+ *
+ * Scores in each {@link GameInput} are parallel to the `teams` order.
+ *
+ * @category Matches
  */
 interface MatchInput {
-    /** Event/tournament name */
-    event: string;
-    /** Bracket/division name */
-    bracket: string;
-    /** Match date and time */
-    date: Date | string;
-    /** Team 1 player IDs (1 for singles, 2 for doubles) */
-    team1: [string] | [string, string];
-    /** Team 2 player IDs (1 for singles, 2 for doubles) */
-    team2: [string] | [string, string];
-    /** Game scores as [team1Score, team2Score] tuples */
-    scores: [number, number][];
-    /** Match type (default: "SIDEOUT") */
-    matchType?: string;
-    /** Match source (default: "PARTNER") */
-    source?: string;
-    /** Location (optional) */
-    location?: string;
-    /** Unique identifier (auto-generated if not provided) */
-    identifier?: string;
+    readonly identifier: string;
+    readonly teams: readonly (readonly string[])[];
+    readonly games: readonly GameInput[];
+    readonly sport?: string;
+    readonly bracket?: string;
+    readonly event?: string;
+    readonly location?: string;
+    readonly matchDate?: string;
+    readonly matchSource?: string;
+    readonly matchType?: string;
+    readonly winScore?: number;
+    readonly winBy?: number;
+    readonly extras?: Readonly<Record<string, unknown>>;
+    readonly originalId?: string;
+    readonly originalType?: string;
+    readonly clubId?: number;
 }
 /**
- * Match data as sent to API.
+ * Compressed bulk match submission.
  *
- * @category Types
+ * Top-level fields are defaults applied to every match in the
+ * {@link matches} list. Any match can override any field. `sport`,
+ * `winScore`, and `winBy` are **required** at the batch level — partners
+ * must tell the rater which sport the matches are in and what the
+ * winning conditions were so scores can be interpreted correctly.
+ *
+ * @category Matches
  */
-interface MatchApiData {
-    identifier: string;
-    bracket: string;
-    event: string;
-    format: 'SINGLES' | 'DOUBLES';
-    matchDate: string;
-    matchSource: string;
-    matchType: string;
-    location?: string;
-    teamA: {
-        player1: string;
-        player2?: string;
-        game1?: number;
-        game2?: number;
-        game3?: number;
-        game4?: number;
-        game5?: number;
-    };
-    teamB: {
-        player1: string;
-        player2?: string;
-        game1?: number;
-        game2?: number;
-        game3?: number;
-        game4?: number;
-        game5?: number;
-    };
-}
-/**
- * Response from match submission.
- *
- * @category Types
- */
-interface MatchResultData {
-    /** Whether submission succeeded */
-    success: boolean;
-    /** Number of matches processed */
-    numMatches: number;
-    /** Total number of games recorded */
-    numGames: number;
-    /** Whether this was a dry-run (validation only) */
-    dryRun?: boolean;
-    /** Human-readable result message */
-    message?: string;
-    /** List of validation/processing errors */
-    errors?: string[];
-}
-/**
- * Rating update from API.
- *
- * @category Types
- */
-interface RatingUpdateData {
-    /** External player ID (vair_mem_xxx format) */
-    id: string;
-    memberName?: string;
-    previousRating?: number;
-    newRating?: number;
-    changedAt?: string;
-    ratingSplits?: RatingSplitsData;
-}
-/**
- * Search results from API.
- *
- * @category Types
- */
-interface SearchResultsData {
-    players: PlayerSearchData[];
-    total: number;
-    page: number;
-    limit: number;
+interface MatchBatch {
+    readonly sport: string;
+    readonly winScore: number;
+    readonly winBy: number;
+    readonly matches: readonly MatchInput[];
+    readonly bracket?: string;
+    readonly event?: string;
+    readonly location?: string;
+    readonly matchDate?: string;
+    readonly matchSource?: string;
+    readonly matchType?: string;
+    readonly extras?: Readonly<Record<string, unknown>>;
+    readonly identifier?: string;
+    readonly originalId?: string;
+    readonly originalType?: string;
+    readonly clubId?: number;
+    readonly dryRun?: boolean;
+}
+/**
+ * Raw result from a batch submission.
+ *
+ * @category Matches
+ */
+interface MatchBatchResultWire {
+    readonly success: boolean;
+    readonly numMatches: number;
+    readonly numGames: number;
+    readonly dryRun?: boolean;
+    readonly message?: string;
+    readonly errors?: readonly string[];
+}
+/**
+ * Filters for {@link LeaderboardResource.list}.
+ *
+ * @category Leaderboards
+ */
+interface LeaderboardOptions {
+    readonly category?: string;
+    readonly ageBracket?: string;
+    readonly scope?: string;
+    readonly state?: string;
+    readonly city?: string;
+    readonly clubId?: string;
+    readonly gender?: Gender | Lowercase<Gender>;
+    readonly verifiedOnly?: boolean;
+    readonly minGames?: number;
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly search?: string;
+}
+/**
+ * Options for {@link LeaderboardResource.rank}.
+ *
+ * @category Leaderboards
+ */
+interface PlayerRankOptions {
+    readonly category?: string;
+    readonly ageBracket?: string;
+    readonly scope?: string;
+    readonly state?: string;
+    readonly city?: string;
+    readonly clubId?: string;
+    /** Number of players on either side of the target. Default 5. */
+    readonly contextSize?: number;
+}
+/**
+ * Error envelope commonly returned by the Partner API on non-2xx status.
+ *
+ * @category Errors
+ */
+interface ApiErrorResponse {
+    readonly message?: string;
+    readonly error?: string;
+    readonly statusCode?: number;
 }
 
 /**
- * Vairified SDK Models
+ * {@link LeaderboardResource} — read-only leaderboard queries.
  *
- * Rich model classes with methods for easy API interaction.
+ * @module
+ */
+
+/**
+ * Read-only leaderboard queries.
+ *
+ * @category Resources
+ */
+declare class LeaderboardResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
+    /** Fetch a leaderboard page with optional filters. */
+    list(options?: LeaderboardOptions): Promise<Record<string, unknown>>;
+    /** Fetch a specific player's rank plus nearby players. */
+    rank(playerId: string, options?: PlayerRankOptions): Promise<Record<string, unknown>>;
+    /** List available leaderboard categories, brackets, and scopes. */
+    categories(): Promise<Record<string, unknown>>;
+}
+
+/**
+ * {@link MatchBatchResult} — result of a batch match submission.
  *
  * @module
  */
 
-/** Union type for player data from different endpoints */
-type PlayerData = MemberData | PlayerSearchData;
 /**
- * A single rating split with metadata.
+ * Result of a {@link MatchesResource.submit} call.
  *
- * @category Models
+ * {@link success} is `true` only when every match in the batch was
+ * accepted. Check {@link errors} for per-match validation failures.
+ *
+ * @category Matches
  */
-declare class RatingSplit {
-    /** The rating value */
-    readonly rating: number;
-    /** Abbreviation (e.g., "VG", "50+") */
-    readonly abbr: string;
-    /** Date of last match in this category */
-    readonly datePlayed?: string;
-    constructor(data: RatingSplitData | number);
-}
-/**
- * Rating breakdown by category.
- *
- * Access ratings by category name or use convenience properties.
- *
- * @category Models
- */
-declare class RatingSplits {
-    /** Map of category names to rating splits */
-    readonly splits: Map<string, RatingSplit>;
-    constructor(data?: RatingSplitsData);
-    /** Get rating for a category */
-    get(category: string): number | undefined;
-    /** Open division rating */
-    get open(): number | undefined;
-    /** Gender-specific rating (same gender doubles) */
-    get gender(): number | undefined;
-    /** Mixed doubles rating */
-    get mixed(): number | undefined;
-    /** Recreational rating */
-    get recreational(): number | undefined;
-    /** Singles rating */
-    get singles(): number | undefined;
-    /** Best available verified rating */
-    get best(): number | undefined;
-    /** Convert to plain object */
-    toJSON(): Record<string, {
-        rating: number;
-        abbr: string;
-    }>;
-}
-/**
- * A player in the Vairified system.
- *
- * From public search, only limited data is available (display name, location, rating).
- * For full profile data, use getMember() with OAuth consent.
- *
- * @category Models
- */
-declare class Player {
-    /** External player ID (vair_mem_xxx format) */
-    readonly id: string;
-    /** Display name (First Name + Last Initial from search) */
-    readonly displayName?: string;
-    /** First name (only from connected member) */
-    readonly firstName?: string;
-    /** Last name (only from connected member) */
-    readonly lastName?: string;
-    /** Primary/overall rating (2.0-8.0) */
-    readonly rating: number;
-    /** Whether player is verified */
-    readonly isVairified: boolean;
-    /** Whether player has connected to your app */
-    readonly isConnected: boolean;
-    /** Ratings by category (only from connected member) */
-    readonly ratingSplits: RatingSplits;
-    /** City */
-    readonly city?: string;
-    /** State code */
-    readonly state?: string;
-    /** Country code */
-    readonly country?: string;
-    protected _client?: Vairified;
-    constructor(data: PlayerData, client?: Vairified);
-    /** Full name (or display name if full name not available) */
-    get name(): string;
-    /** Best verified rating */
-    get verifiedRating(): number | undefined;
+declare class MatchBatchResult {
+    readonly success: boolean;
+    readonly numMatches: number;
+    readonly numGames: number;
+    readonly dryRun: boolean | null;
+    readonly message: string | null;
+    readonly errors: readonly string[] | null;
+    constructor(wire: MatchBatchResultWire);
+    /** Shorthand: successful submission with zero errors. */
+    get ok(): boolean;
+    /** Whether this was a dry-run (validation only, nothing persisted). */
+    get isDryRun(): boolean;
     toString(): string;
 }
+
 /**
- * A member with full profile access (requires OAuth connection).
+ * {@link MatchesResource} — bulk match submission.
  *
- * Only accessible for players who have connected their account via OAuth.
+ * @module
+ */
+
+/**
+ * Match submission — one call submits a full batch.
  *
- * @category Models
+ * @category Resources
  */
-declare class Member extends Player {
-    /** Email address (only if profile:email scope granted) */
-    readonly email?: string;
-    /** Scopes the player granted to your app */
-    readonly grantedScopes: string[];
-    constructor(data: MemberData, client?: Vairified);
-    /** Check if the player has granted a specific scope */
-    hasScope(scope: string): boolean;
-    /** Refresh member data from API */
-    refresh(): Promise<Member>;
+declare class MatchesResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
+    /**
+     * Submit a {@link MatchBatch} for rating calculation.
+     *
+     * All players in every match must have granted the `match:submit`
+     * scope via OAuth (unless your API key has the
+     * `match:submit:trusted` scope, which skips per-player consent).
+     *
+     * Set `batch.dryRun = true` to validate without persisting.
+     *
+     * ```ts
+     * const result = await client.matches.submit({
+     *   sport: 'pickleball',
+     *   winScore: 11,
+     *   winBy: 2,
+     *   bracket: '4.0 Doubles',
+     *   event: 'Weekly League',
+     *   matchDate: '2026-04-11T14:00:00Z',
+     *   matches: [
+     *     {
+     *       identifier: 'm1',
+     *       teams: [['vair_mem_aaa', 'vair_mem_bbb'],
+     *               ['vair_mem_ccc', 'vair_mem_ddd']],
+     *       games: [{ scores: [11, 8] }, { scores: [11, 5] }],
+     *     },
+     *   ],
+     * });
+     * if (result.ok) {
+     *   console.log(`Submitted ${result.numGames} games`);
+     * }
+     * ```
+     */
+    submit(batch: MatchBatch): Promise<MatchBatchResult>;
+    /** Send a test payload to a webhook URL. */
+    testWebhook(webhookUrl: string): Promise<Record<string, unknown>>;
+}
+
+/**
+ * {@link SportRating} — a player's ratings for one sport.
+ *
+ * @module
+ */
+
+/**
+ * A player's ratings for a single sport.
+ *
+ * The top-level `rating` / `abbr` is the primary rating for that sport
+ * (conventionally the overall-open bracket). Every category × age
+ * bracket the player has played is also available via {@link get},
+ * {@link has}, subscript-style access, and iteration.
+ *
+ * ```ts
+ * const pb = member.sport.get('pickleball');
+ * if (pb) {
+ *   console.log(pb.rating, pb.abbr);                 // 3.915 VO
+ *   console.log(pb.get('overall-open')?.rating);     // 3.915
+ *   console.log(pb.has('singles-40+'));              // false
+ *   console.log(pb.size);                            // 3
+ *   for (const [key, split] of pb) {
+ *     console.log(key, split.rating);
+ *   }
+ * }
+ * ```
+ *
+ * @category Members
+ */
+declare class SportRating {
+    #private;
+    /** Primary rating for this sport. */
+    readonly rating: number;
+    /** Category abbreviation for the primary rating (e.g. `'VO'`). */
+    readonly abbr: string;
+    constructor(wire: SportRatingWire);
+    /**
+     * Look up a rating split by key (e.g. `'overall-open'`,
+     * `'singles-12-13'`, `'gender-40+'`). Returns `undefined` if the
+     * player has no rating for that bracket.
+     */
+    get(key: string): RatingSplitWire | undefined;
+    /** Whether the player has a rating for the given split key. */
+    has(key: string): boolean;
+    /** Number of rating splits. */
+    get size(): number;
+    /** All split keys the player has ratings for. */
+    keys(): IterableIterator<string>;
+    /** All rating splits the player has. */
+    values(): IterableIterator<RatingSplitWire>;
+    /** `[key, split]` pairs for every rating split. */
+    entries(): IterableIterator<[string, RatingSplitWire]>;
+    /**
+     * `for (const [key, split] of sportRating) { ... }` — iterate every
+     * rating split the player has in this sport.
+     */
+    [Symbol.iterator](): IterableIterator<[string, RatingSplitWire]>;
 }
+
+/**
+ * {@link Member} — partner-facing player record.
+ *
+ * @module
+ */
+
 /**
- * A match to submit to the Vairified Partner API.
+ * Map-like wrapper around a player's sport → {@link SportRating}.
  *
- * @category Models
+ * Supports `.get(code)`, `.has(code)`, `.size`, and iteration so the
+ * shape feels native:
  *
- * @example
  * ```ts
- * // Doubles match: 11-9, 11-7
- * const match = new Match({
- *   event: 'Weekly League',
- *   bracket: '4.0 Doubles',
- *   date: new Date(),
- *   team1: ['player1_id', 'player2_id'],
- *   team2: ['player3_id', 'player4_id'],
- *   scores: [[11, 9], [11, 7]],
- * });
- *
- * // Singles match: 11-8, 9-11, 11-6
- * const match = new Match({
- *   event: 'Club Singles',
- *   bracket: 'Open Singles',
- *   date: new Date(),
- *   team1: ['player1_id'],
- *   team2: ['player2_id'],
- *   scores: [[11, 8], [9, 11], [11, 6]],
- * });
+ * member.sport.get('pickleball')?.rating
+ * for (const [code, rating] of member.sport) { ... }
  * ```
+ *
+ * @category Members
  */
-declare class Match {
-    /** Event/tournament name */
-    readonly event: string;
-    /** Bracket/division name */
-    readonly bracket: string;
-    /** Match date */
-    readonly date: Date;
-    /** Team 1 player IDs */
-    readonly team1: readonly string[];
-    /** Team 2 player IDs */
-    readonly team2: readonly string[];
-    /** Game scores */
-    readonly scores: readonly [number, number][];
-    /** Match type */
-    readonly matchType: string;
-    /** Match source */
-    readonly source: string;
-    /** Location */
-    readonly location?: string;
-    /** Unique identifier */
-    readonly identifier: string;
-    /** Match ID (set after submission) */
-    id?: string;
-    constructor(data: MatchInput);
-    /** Match format: SINGLES or DOUBLES */
-    get format(): 'SINGLES' | 'DOUBLES';
-    /** Team that won (1 or 2). Returns 0 if tie. */
-    get winner(): 0 | 1 | 2;
-    /** Score summary like "11-9, 11-7" */
-    get scoreSummary(): string;
-    /** Convert to API request format */
-    toJSON(): MatchApiData;
+declare class MemberSportMap {
+    #private;
+    constructor(wire: Readonly<Record<string, SportRatingWire>> | undefined);
+    get(sport: string): SportRating | undefined;
+    has(sport: string): boolean;
+    get size(): number;
+    keys(): IterableIterator<string>;
+    values(): IterableIterator<SportRating>;
+    entries(): IterableIterator<[string, SportRating]>;
+    [Symbol.iterator](): IterableIterator<[string, SportRating]>;
 }
 /**
- * Result of a match submission.
+ * A partner-facing player record.
  *
- * @category Models
+ * Returned by {@link MembersResource.get} (full detail, requires an
+ * active OAuth connection) and {@link MembersResource.search} (limited
+ * detail for public search).
+ *
+ * Rating data lives under {@link sport} — keyed by sport code. The
+ * backend returns only the sports the player has ratings in, or only
+ * the sports requested via the `sport=` query filter. Use
+ * {@link ratingFor} to fetch the primary rating for a specific sport
+ * with a sensible default.
+ *
+ * @category Members
  */
-declare class MatchResult {
-    /** Whether submission succeeded */
-    readonly success: boolean;
-    /** Number of matches processed */
-    readonly numMatches: number;
-    /** Number of games recorded */
-    readonly numGames: number;
-    /** Whether this was a dry-run (validation only) */
-    readonly dryRun: boolean;
-    /** Human-readable result message */
-    readonly message?: string;
-    /** List of validation/processing errors */
-    readonly errors: string[];
-    constructor(data: MatchResultData);
-    /** Alias for dryRun */
-    get isDryRun(): boolean;
-    /** Returns true if submission succeeded without errors */
-    get ok(): boolean;
+declare class Member {
+    readonly memberId: number;
+    readonly id: string | null;
+    readonly firstName: string;
+    readonly lastName: string;
+    readonly fullName: string;
+    readonly displayName: string;
+    readonly age: number | null;
+    readonly city: string | null;
+    readonly state: string | null;
+    readonly zip: string | null;
+    readonly country: string | null;
+    readonly gender: Gender | null;
+    readonly status: MemberStatusWire;
+    readonly sport: MemberSportMap;
+    readonly activeLeagues: readonly string[] | null;
+    readonly email: string | null;
+    readonly grantedScopes: readonly string[] | null;
+    constructor(wire: PartnerMemberWire);
+    /** Full name — alias for {@link fullName}, matching common usage. */
+    get name(): string;
+    /** The list of sport codes this player has ratings in. */
+    get sports(): readonly string[];
+    /**
+     * Primary rating for a given sport.
+     *
+     * @param sport Sport code — defaults to `'pickleball'`.
+     * @returns The primary rating value, or `null` if the player has no
+     *   ratings for that sport.
+     */
+    ratingFor(sport?: string): number | null;
+    /**
+     * Get a specific rating split for a sport.
+     *
+     * @param key Split key (e.g. `'overall-open'`).
+     * @param sport Sport code — defaults to `'pickleball'`.
+     */
+    split(key: string, sport?: string): RatingSplitWire | null;
+    /** Compact summary for console output. */
+    toString(): string;
 }
+
 /**
- * A rating change notification.
+ * {@link RatingUpdate} — a single rating change notification.
  *
- * @category Models
+ * @module
+ */
+
+/**
+ * A single rating change notification.
+ *
+ * Returned by {@link MembersResource.ratingUpdates} (polling) and
+ * delivered via webhook callbacks to partners that have registered a
+ * webhook URL and have subscribers.
+ *
+ * @category Members
  */
 declare class RatingUpdate {
-    /** External player ID (vair_mem_xxx format) */
-    readonly id: string;
-    /** Member name */
-    readonly memberName?: string;
-    /** Previous rating */
-    readonly previousRating: number;
-    /** New rating */
-    readonly newRating: number;
-    /** When the change occurred */
-    readonly changedAt: Date;
-    /** Updated rating splits */
-    readonly ratingSplits: RatingSplits;
-    private _client?;
-    constructor(data: RatingUpdateData, client?: Vairified);
-    /** Amount of rating change */
-    get change(): number;
-    /** Whether rating improved */
+    readonly memberId: number;
+    readonly id: string | null;
+    readonly displayName: string | null;
+    readonly sport: string | null;
+    readonly previousRating: number | null;
+    readonly newRating: number | null;
+    readonly changedAt: string | null;
+    readonly ratingSplits: Readonly<Record<string, RatingSplitWire>> | null;
+    constructor(wire: PartnerRatingUpdateWire);
+    /**
+     * Rating change amount — `newRating - previousRating`. Returns `null`
+     * if either rating is missing from the update payload.
+     */
+    get delta(): number | null;
+    /** `true` when the new rating is strictly higher than the previous. */
     get improved(): boolean;
-    /** Fetch the member associated with this update */
-    getMember(): Promise<Member>;
     toString(): string;
 }
+
 /**
- * Paginated search results.
- *
- * @category Models
- */
-declare class SearchResults implements Iterable<Player> {
-    /** List of players */
-    readonly players: Player[];
-    /** Total matching players */
-    readonly total: number;
-    /** Current page */
-    readonly page: number;
-    /** Results per page */
-    readonly limit: number;
-    private _client?;
-    private _filters;
-    constructor(data: SearchResultsData, client?: Vairified, filters?: SearchFilters);
-    /** Whether more results are available */
-    get hasMore(): boolean;
-    /** Total number of pages */
-    get pages(): number;
-    /** Number of players in current page */
-    get length(): number;
-    /** Get player by index */
-    at(index: number): Player | undefined;
-    /** Iterate over players */
-    [Symbol.iterator](): Iterator<Player>;
-    /** Fetch next page of results */
-    nextPage(): Promise<SearchResults>;
+ * {@link MembersResource} — member lookups, search, and rating updates.
+ *
+ * @module
+ */
+
+/**
+ * Member operations — get a single member, auto-paginating search,
+ * find by name, and polling for rating change notifications.
+ *
+ * @category Resources
+ */
+declare class MembersResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
+    /**
+     * Get a connected member by external ID.
+     *
+     * **Requires an active OAuth connection** between your partner app
+     * and the player. Use the OAuth flow on `client.oauth` first.
+     *
+     * @param playerId External player ID in `vair_mem_xxx` format.
+     * @param options.sport Optional sport filter — single code or list.
+     *   When omitted, the response contains every sport the player has
+     *   ratings in.
+     * @throws {@link NotFoundError} if the external ID is unknown.
+     * @throws {@link VairifiedError} if the player has not connected to
+     *   your app (403) or the request otherwise fails.
+     *
+     * @example
+     * ```ts
+     * const member = await client.members.get('vair_mem_xxx');
+     * console.log(member.name, member.ratingFor('pickleball'));
+     *
+     * // Just pickleball
+     * const member2 = await client.members.get('vair_mem_xxx', { sport: 'pickleball' });
+     *
+     * // Multiple sports
+     * const member3 = await client.members.get('vair_mem_xxx', {
+     *   sport: ['pickleball', 'padel'],
+     * });
+     * ```
+     */
+    get(playerId: string, options?: {
+        sport?: string | readonly string[];
+    }): Promise<Member>;
+    /**
+     * Search for members, yielding each match as a {@link Member}.
+     *
+     * This is an **auto-paginating async iterator** — it fetches pages
+     * from the server lazily as you iterate, so you can stream through
+     * thousands of results without holding them all in memory:
+     *
+     * ```ts
+     * for await (const m of client.members.search({ city: 'Austin' })) {
+     *   console.log(m.name, m.ratingFor('pickleball'));
+     * }
+     * ```
+     *
+     * Stop early by `break`-ing out of the loop, or cap the total with
+     * `maxResults`.
+     */
+    search(filters?: SearchFilters): AsyncGenerator<Member, void, void>;
+    /**
+     * Return the first search hit for a name, or `null`.
+     *
+     * Convenience for the common "look up by name" case:
+     *
+     * ```ts
+     * const mike = await client.members.find('Mike Barker');
+     * if (mike) {
+     *   console.log(mike.ratingFor('pickleball'));
+     * }
+     * ```
+     */
+    find(name: string): Promise<Member | null>;
+    /**
+     * Poll for rating change notifications.
+     *
+     * Returns a list of {@link RatingUpdate} objects for every player
+     * whose rating has changed since the last poll. Members are
+     * considered subscribed when they have an active OAuth connection
+     * with the `webhook:subscribe` scope.
+     */
+    ratingUpdates(): Promise<readonly RatingUpdate[]>;
 }
 
 /**
- * Vairified OAuth Helpers
+ * Vairified OAuth helpers and type definitions.
  *
- * Utilities for implementing the "Connect with Vairified" OAuth flow.
+ * Use the {@link OAuthResource} on `client.oauth` for the full flow —
+ * these helpers exist for partners who need to build authorization URLs
+ * or validate scopes outside the client (e.g. in a frontend that only
+ * handles the redirect step).
  *
  * @module
  */
 /**
- * Available OAuth scopes with descriptions.
+ * Every OAuth scope the Vairified authorization server accepts.
+ *
+ * Declaring this as a string union (rather than a free-form `string`)
+ * lets TypeScript catch typos at authoring time:
+ *
+ * ```ts
+ * const scopes: OAuthScope[] = ['profile:read', 'rating:read']; // ok
+ * const bad: OAuthScope[] = ['profile:read', 'rating']; // type error
+ * ```
  *
  * @category OAuth
  */
-declare const SCOPES: {
-    readonly 'profile:read': "Access your name, location, and verification status";
-    readonly 'profile:email': "Access your email address";
-    readonly 'rating:read': "View your current rating and rating splits";
-    readonly 'rating:history': "View your complete rating history";
-    readonly 'match:submit': "Submit match results on your behalf";
-    readonly 'webhook:subscribe': "Receive notifications when your rating changes";
-};
+type OAuthScope = 'profile:read' | 'profile:email' | 'rating:read' | 'rating:history' | 'match:submit' | 'webhook:subscribe';
 /**
- * Available OAuth scope keys.
+ * Human-readable description for every OAuth scope.
  *
  * @category OAuth
  */
-type OAuthScope = keyof typeof SCOPES;
+declare const SCOPES: Readonly<Record<OAuthScope, string>>;
 /**
- * Default scopes requested for new connections.
+ * The scopes automatically requested when none are specified.
  *
  * @category OAuth
  */
-declare const DEFAULT_SCOPES: OAuthScope[];
+declare const DEFAULT_SCOPES: readonly OAuthScope[];
 /**
- * OAuth configuration for a partner application.
+ * Configuration for building an authorization URL manually.
  *
  * @category OAuth
  */
 interface OAuthConfig {
-    /** Partner API key */
-    apiKey: string;
-    /** Your application's callback URL */
-    redirectUri: string;
-    /** Vairified API base URL */
-    baseUrl?: string;
+    readonly apiKey: string;
+    readonly redirectUri: string;
+    readonly baseUrl?: string;
 }
 /**
- * Response from starting an OAuth authorization.
+ * Response from starting an OAuth authorization flow.
  *
  * @category OAuth
  */
 interface AuthorizationResponse {
-    /** Full URL to redirect the user to */
-    authorizationUrl: string;
-    /** Authorization code (for internal tracking) */
-    code: string;
-    /** CSRF state parameter */
-    state?: string;
+    readonly authorizationUrl: string;
+    readonly code: string;
+    readonly state?: string;
 }
 /**
  * Response from exchanging an authorization code for tokens.
@@ -540,443 +784,236 @@ interface AuthorizationResponse {
  * @category OAuth
  */
 interface TokenResponse {
-    /** Access token for API requests */
-    accessToken: string;
-    /** Refresh token for obtaining new access tokens */
-    refreshToken?: string;
-    /** Token expiration in seconds */
-    expiresIn: number;
-    /** Granted scopes */
-    scope: string[];
-    /** Connected player's external ID */
-    playerId: string;
+    readonly accessToken: string;
+    readonly refreshToken: string | null;
+    readonly expiresIn: number;
+    readonly scope: readonly string[];
+    readonly playerId: string;
 }
 /**
  * Build the URL to redirect users to for OAuth authorization.
  *
- * This is a helper for building the URL manually. In most cases,
- * you should use the Vairified client's OAuth methods instead.
- *
- * @param config - OAuth configuration
- * @param scopes - Permission scopes to request
- * @param state - CSRF protection state parameter
- * @returns URL to redirect the user to
- *
- * @example
- * ```ts
- * const url = getAuthorizationUrl(
- *   {
- *     apiKey: 'vair_pk_xxx',
- *     redirectUri: 'https://myapp.com/oauth/callback',
- *   },
- *   ['profile:read', 'rating:read'],
- * );
- * // Redirect user to this URL
- * window.location.href = url;
- * ```
+ * Prefer {@link OAuthResource.authorize} on a Vairified client — this
+ * helper is only useful when you need to construct the URL without
+ * making an HTTP call first (for example, in a pure-frontend handoff).
  *
  * @category OAuth
  */
-declare function getAuthorizationUrl(config: OAuthConfig, scopes?: OAuthScope[], state?: string): string;
+declare function getAuthorizationUrl(config: OAuthConfig, options?: {
+    scopes?: readonly OAuthScope[];
+    state?: string;
+}): string;
 /**
- * Check if a scope is valid.
- *
- * @param scope - Scope string to validate
- * @returns True if scope is valid
+ * Check whether a scope string is one the Vairified server accepts.
  *
  * @category OAuth
  */
 declare function validateScope(scope: string): scope is OAuthScope;
 /**
- * Get a human-readable description of a scope.
+ * Get a human-readable description of an OAuth scope.
  *
- * @param scope - Scope string
- * @returns Description of what the scope grants access to
+ * Returns `"Unknown scope: {scope}"` for unrecognized scopes so this
+ * function is safe to call on user-supplied input.
  *
  * @category OAuth
  */
-declare function describeScope(scope: OAuthScope): string;
+declare function describeScope(scope: string): string;
 /**
- * Get descriptions for multiple scopes.
- *
- * @param scopes - List of scope strings
- * @returns Array of objects with scope and description
+ * Describe multiple scopes at once.
  *
  * @category OAuth
  */
-declare function describeScopes(scopes: OAuthScope[]): Array<{
-    scope: OAuthScope;
+declare function describeScopes(scopes: readonly string[]): readonly {
+    scope: string;
     description: string;
-}>;
+}[];
 /**
- * Generate a random state parameter for CSRF protection.
+ * Generate a cryptographically-random CSRF state token suitable for
+ * use with {@link OAuthResource.authorize}.
  *
- * @returns Random 32-character hexadecimal string
+ * Uses the Web Crypto API (available in Node 19+ and all modern
+ * browsers). The returned string is URL-safe base64 of 32 random bytes.
  *
  * @category OAuth
  */
 declare function generateState(): string;
 
 /**
- * Vairified SDK Client
+ * {@link OAuthResource} — OAuth 2.0 flow for player consent.
  *
- * Main client for the Vairified Partner API.
+ * @module
+ */
+
+/**
+ * OAuth 2.0 flow for obtaining player consent.
+ *
+ * Typical flow:
+ *
+ * 1. {@link authorize} — start an authorization, get a URL to redirect
+ *    the player to.
+ * 2. Player approves on the Vairified site and is redirected back to
+ *    your `redirectUri` with a `code` query parameter.
+ * 3. {@link exchangeToken} — swap the code for access and refresh
+ *    tokens plus the player's external ID.
+ * 4. Store the refresh token and call {@link refresh} when the access
+ *    token expires.
+ * 5. {@link revoke} — disconnect a player from your app.
+ *
+ * @category Resources
+ */
+declare class OAuthResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
+    /**
+     * Start an OAuth authorization flow.
+     *
+     * @throws {@link OAuthError} with `errorCode: 'invalid_scope'` if a
+     *   requested scope is not in the accepted list.
+     */
+    authorize(options: {
+        redirectUri: string;
+        scopes?: readonly OAuthScope[];
+        state?: string;
+    }): Promise<AuthorizationResponse>;
+    /** Exchange an authorization code for access and refresh tokens. */
+    exchangeToken(options: {
+        code: string;
+        redirectUri: string;
+    }): Promise<TokenResponse>;
+    /** Refresh an expired access token using a refresh token. */
+    refresh(refreshToken: string): Promise<TokenResponse>;
+    /** Revoke a player's OAuth connection to your app. */
+    revoke(playerId: string): Promise<Record<string, unknown>>;
+    /** Return the list of OAuth scopes the server currently supports. */
+    availableScopes(): Promise<readonly {
+        name: string;
+        description: string;
+    }[]>;
+}
+
+/**
+ * {@link Vairified} — the main entry point of the SDK.
  *
  * @module
  */
 
-declare const ENVIRONMENTS: {
-    readonly production: "https://api-next.vairified.com/api/v1";
-    readonly staging: "https://api-staging.vairified.com/api/v1";
-    readonly local: "http://localhost:3001/api/v1";
-};
 /**
- * Available environment presets for the Vairified client.
+ * Environment preset → base URL mapping.
+ *
+ * Partners can switch between production, staging, and local development
+ * without memorizing hostnames.
  *
  * @category Client
  */
-type VairifiedEnvironment = keyof typeof ENVIRONMENTS;
+declare const ENVIRONMENTS: Readonly<Record<VairifiedEnvironment, string>>;
 /**
- * Client for the Vairified Partner API.
+ * Async client for the Vairified Partner API.
  *
- * @category Client
+ * The client is organized around sub-resources that mirror the REST
+ * structure — {@link members}, {@link matches}, {@link oauth},
+ * {@link leaderboard}. Each sub-resource is a thin wrapper around the
+ * HTTP transport on this object.
  *
- * @example
- * ```ts
- * const client = new Vairified({ apiKey: 'vair_pk_xxx' });
+ * ## Lifecycle
  *
- * // Get a member
- * const member = await client.getMember('user_123');
- * console.log(member.name, member.rating);
+ * The client holds no persistent connections itself — it's safe to
+ * create one per request if you want. But for typical usage, wrap it
+ * in `await using` so resources are cleaned up deterministically:
  *
- * // Search for players
- * const results = await client.search({ city: 'Austin', ratingMin: 4.0 });
- * for (const player of results) {
- *   console.log(player.name, player.rating);
- * }
+ * ```ts
+ * await using client = new Vairified({ apiKey: 'vair_pk_xxx' });
+ *
+ * const member = await client.members.get('vair_mem_xxx');
+ * console.log(member.name, member.ratingFor('pickleball'));
  *
- * // Submit a match (doubles: 11-9, 11-7)
- * const match = new Match({
- *   event: 'Weekly League',
- *   bracket: '4.0 Doubles',
- *   date: new Date(),
- *   team1: ['p1', 'p2'],
- *   team2: ['p3', 'p4'],
- *   scores: [[11, 9], [11, 7]],
- * });
- * const result = await client.submitMatch(match);
- * if (result.ok) {
- *   console.log(`Submitted ${result.numGames} games`);
+ * for await (const m of client.members.search({ city: 'Austin' })) {
+ *   console.log(m.name);
  * }
  * ```
  *
- * @remarks
- * If your API key has the "dry-run" scope, match submissions will be
- * validated but not persisted. This is useful for testing integrations.
+ * `await using` requires TypeScript 5.2+ and Node 20+. If you can't
+ * use it, just call `await client.close()` manually when you're done.
+ *
+ * @category Client
  */
 declare class Vairified {
-    /** API key */
+    #private;
+    /** The resolved API key this client is using. */
     readonly apiKey: string;
-    /** Base URL */
+    /** The resolved base URL (production, staging, local, or custom). */
     readonly baseUrl: string;
-    /** Environment name */
+    /** The resolved environment name. */
     readonly env: VairifiedEnvironment;
-    /** Request timeout in ms */
-    readonly timeout: number;
+    /** Request timeout in milliseconds. */
+    readonly timeoutMs: number;
+    /** Member operations — get, search, find, ratingUpdates. */
+    readonly members: MembersResource;
+    /** Match submission — submit, testWebhook. */
+    readonly matches: MatchesResource;
+    /** OAuth flow — authorize, exchangeToken, refresh, revoke. */
+    readonly oauth: OAuthResource;
+    /** Leaderboard queries — list, rank, categories. */
+    readonly leaderboard: LeaderboardResource;
     constructor(options?: VairifiedOptions);
-    private getEnvVar;
-    private getEnvApiKey;
-    private getHeaders;
-    private handleError;
-    private request;
-    /**
-     * Get a connected member by their external ID.
-     *
-     * **Requires OAuth Connection**: The player must have connected their
-     * account to your application via OAuth before you can access their data.
-     *
-     * @param playerId - External player ID (vair_mem_xxx format)
-     * @returns Member object with profile and rating data
-     * @throws NotFoundError if member is not found or invalid ID format
-     * @throws ForbiddenError if player has not connected to your app
-     *
-     * @example
-     * ```ts
-     * const member = await client.getMember('vair_mem_0ABC123def456GHI789jk');
-     * console.log(member.name, member.rating);
-     * console.log(member.ratingSplits.open); // Open division rating
-     * console.log(member.grantedScopes); // ['profile:read', 'rating:read']
-     * ```
-     */
-    getMember(playerId: string): Promise<Member>;
-    /**
-     * Search for players.
-     *
-     * @param filters - Search filters
-     * @returns SearchResults with players and pagination
-     *
-     * @example
-     * ```ts
-     * const results = await client.search({
-     *   city: 'Austin',
-     *   ratingMin: 4.0,
-     *   vairifiedOnly: true,
-     * });
-     *
-     * for (const player of results) {
-     *   console.log(player.name, player.rating);
-     * }
-     *
-     * // Pagination
-     * if (results.hasMore) {
-     *   const nextPage = await results.nextPage();
-     * }
-     * ```
-     */
-    search(filters?: SearchFilters): Promise<SearchResults>;
-    /**
-     * Find a single player by name.
-     *
-     * @param name - Player name to search for
-     * @returns Player if found, undefined otherwise
-     *
-     * @example
-     * ```ts
-     * const player = await client.findPlayer('John Smith');
-     * if (player) {
-     *   console.log(player.rating);
-     * }
-     * ```
-     */
-    findPlayer(name: string): Promise<Player | undefined>;
-    /**
-     * Submit a single match.
-     *
-     * @param match - Match object with teams and scores
-     * @returns MatchResult with submission status
-     *
-     * @example
-     * ```ts
-     * const match = new Match({
-     *   event: 'Weekly League',
-     *   bracket: '4.0 Doubles',
-     *   date: new Date(),
-     *   team1: ['p1', 'p2'],
-     *   team2: ['p3', 'p4'],
-     *   scores: [[11, 9], [11, 7]],
-     * });
-     *
-     * const result = await client.submitMatch(match);
-     * if (result.ok) {
-     *   console.log(`Submitted ${result.numGames} games`);
-     * }
-     * ```
-     */
-    submitMatch(match: Match): Promise<MatchResult>;
-    /**
-     * Submit multiple matches in a batch.
-     *
-     * @param matches - List of Match objects
-     * @returns MatchResult with submission status
-     *
-     * @example
-     * ```ts
-     * const result = await client.submitMatches([match1, match2, match3]);
-     * console.log(`Submitted ${result.numGames} games from ${result.numMatches} matches`);
-     *
-     * if (result.dryRun) {
-     *   console.log('This was a dry run - no data persisted');
-     * }
-     * ```
-     */
-    submitMatches(matches: Match[]): Promise<MatchResult>;
-    /**
-     * Get rating updates for subscribed members.
-     *
-     * Members are subscribed when you call getMember().
-     *
-     * @returns List of RatingUpdate objects
-     *
-     * @example
-     * ```ts
-     * const updates = await client.getRatingUpdates();
-     * for (const update of updates) {
-     *   console.log(`${update.memberId}: ${update.previousRating} → ${update.newRating}`);
-     *   if (update.improved) {
-     *     const member = await update.getMember();
-     *     console.log(`${member.name} improved!`);
-     *   }
-     * }
-     * ```
-     */
-    getRatingUpdates(): Promise<RatingUpdate[]>;
-    /**
-     * Test webhook endpoint.
-     *
-     * @param webhookUrl - URL to send test webhook to
-     * @returns Test result
-     */
-    testWebhook(webhookUrl: string): Promise<Record<string, unknown>>;
-    /**
-     * Start an OAuth authorization flow.
-     *
-     * This creates a pending authorization and returns the URL where
-     * users should be redirected to approve access.
-     *
-     * @param redirectUri - Your application's callback URL
-     * @param scopes - Permission scopes to request (defaults to profile:read, rating:read)
-     * @param state - CSRF protection state parameter (recommended)
-     * @returns AuthorizationResponse with the URL to redirect users to
-     * @throws OAuthError if the authorization fails to start
-     *
-     * @example
-     * ```ts
-     * const auth = await client.startOAuth(
-     *   'https://myapp.com/callback',
-     *   ['profile:read', 'rating:read', 'match:submit'],
-     *   'random_csrf_token',
-     * );
-     * // Redirect user to auth.authorizationUrl
-     * window.location.href = auth.authorizationUrl;
-     * ```
-     *
-     * @category OAuth
-     */
-    startOAuth(redirectUri: string, scopes?: OAuthScope[], state?: string): Promise<AuthorizationResponse>;
     /**
-     * Exchange an authorization code for access and refresh tokens.
-     *
-     * Call this after the user approves access and is redirected back
-     * to your application with a code parameter.
-     *
-     * @param code - Authorization code from the callback URL
-     * @param redirectUri - Must match the redirectUri used in startOAuth
-     * @returns TokenResponse with access_token, refresh_token, and player_id
-     * @throws OAuthError if the code is invalid or expired
-     *
-     * @example
-     * ```ts
-     * // After user is redirected to: https://myapp.com/callback?code=xxx
-     * const tokens = await client.exchangeToken(
-     *   new URL(window.location.href).searchParams.get('code')!,
-     *   'https://myapp.com/callback',
-     * );
-     * // Store tokens.accessToken and tokens.refreshToken securely
-     * // Use tokens.playerId to identify the connected player
-     * ```
-     *
-     * @category OAuth
-     */
-    exchangeToken(code: string, redirectUri: string): Promise<TokenResponse>;
-    /**
-     * Refresh an expired access token.
-     *
-     * Use this when an access token expires to obtain a new one
-     * without requiring the user to re-authorize.
-     *
-     * @param refreshToken - The refresh token from a previous token exchange
-     * @returns TokenResponse with new access_token and optionally a new refresh_token
-     * @throws OAuthError if the refresh token is invalid or revoked
-     *
-     * @example
-     * ```ts
-     * try {
-     *   const newTokens = await client.refreshAccessToken(storedRefreshToken);
-     *   // Update stored tokens
-     * } catch (e) {
-     *   if (e instanceof OAuthError && e.errorCode === 'invalid_grant') {
-     *     // Refresh token revoked, user needs to re-authorize
-     *   }
-     * }
-     * ```
-     *
-     * @category OAuth
-     */
-    refreshAccessToken(refreshToken: string): Promise<TokenResponse>;
-    /**
-     * Revoke a player's OAuth connection.
-     *
-     * This disconnects the player from your application. You will no
-     * longer be able to access their data or submit matches on their behalf.
+     * API usage statistics for the current API key.
      *
-     * @param playerId - The player's external ID (vair_mem_xxx format)
-     * @throws OAuthError if the revocation fails
-     *
-     * @example
-     * ```ts
-     * await client.revokeConnection('vair_mem_0ABC123def456GHI789jk');
-     * // Player is now disconnected
-     * ```
-     *
-     * @category OAuth
+     * Returns rate-limit status, request counts, and quota usage.
      */
-    revokeConnection(playerId: string): Promise<void>;
+    usage(): Promise<Record<string, unknown>>;
     /**
-     * Get a list of available OAuth scopes.
-     *
-     * @returns List of scope objects with id, name, and description
+     * Release any resources held by the client.
      *
-     * @example
-     * ```ts
-     * const scopes = await client.getAvailableScopes();
-     * for (const scope of scopes) {
-     *   console.log(`${scope.id}: ${scope.description}`);
-     * }
-     * ```
-     *
-     * @category OAuth
+     * The current transport is stateless, so this is a no-op today, but
+     * partners should still call it (or use `await using`) so the SDK
+     * can add connection pooling later without breaking them.
      */
-    getAvailableScopes(): Promise<Array<{
-        id: string;
-        name: string;
-        description: string;
-    }>>;
+    close(): Promise<void>;
     /**
-     * Get API usage statistics for your partner account.
-     *
-     * @returns Usage statistics (requests, limits, etc.)
-     *
-     * @example
-     * ```ts
-     * const usage = await client.getUsage();
-     * console.log(`Requests today: ${usage.requestsToday}`);
-     * console.log(`Rate limit: ${usage.rateLimit}/hour`);
-     * ```
-     *
-     * @category Client
+     * Explicit resource management hook — enables
+     * `await using client = new Vairified({ ... })` (TypeScript 5.2+).
      */
-    getUsage(): Promise<Record<string, unknown>>;
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Compact summary for console output. */
+    toString(): string;
 }
 
 /**
- * Vairified SDK Errors
+ * Vairified SDK — error hierarchy.
+ *
+ * All SDK errors inherit from {@link VairifiedError}, so a single
+ * `catch (err: unknown) { if (err instanceof VairifiedError) ... }`
+ * covers everything. HTTP-status-specific subclasses (auth, not found,
+ * rate limit, validation) are thrown automatically by the HTTP layer.
  *
  * @module
  */
 /**
- * Base error class for Vairified SDK errors.
+ * Base class for every error thrown by the Vairified SDK.
  *
  * @category Errors
  */
 declare class VairifiedError extends Error {
-    /** HTTP status code */
-    statusCode?: number;
-    /** Response body */
-    response?: unknown;
+    /** HTTP status code (if the error came from an API response). */
+    readonly statusCode?: number;
+    /** Raw response body parsed as JSON when available. */
+    readonly response?: unknown;
     constructor(message: string, statusCode?: number, response?: unknown);
 }
 /**
- * Error thrown when API rate limit is exceeded.
+ * Thrown on HTTP 429 responses. Carries the `Retry-After` header value
+ * when the server provides one.
  *
  * @category Errors
  */
 declare class RateLimitError extends VairifiedError {
-    /** Seconds to wait before retrying */
-    retryAfter?: number;
+    /** Seconds to wait before retrying, or `undefined` if the server didn't say. */
+    readonly retryAfter?: number;
     constructor(message?: string, retryAfter?: number, response?: unknown);
 }
 /**
- * Error thrown when API key is invalid or missing.
+ * Thrown on HTTP 401 — invalid or missing API key.
  *
  * @category Errors
  */
@@ -984,7 +1021,7 @@ declare class AuthenticationError extends VairifiedError {
     constructor(message?: string, response?: unknown);
 }
 /**
- * Error thrown when a requested resource is not found.
+ * Thrown on HTTP 404 — the resource doesn't exist.
  *
  * @category Errors
  */
@@ -992,7 +1029,9 @@ declare class NotFoundError extends VairifiedError {
     constructor(message?: string, response?: unknown);
 }
 /**
- * Error thrown when request validation fails.
+ * Thrown on HTTP 400 — the server rejected the request payload.
+ *
+ * Inspect {@link VairifiedError.response} for field-level details.
  *
  * @category Errors
  */
@@ -1000,16 +1039,18 @@ declare class ValidationError extends VairifiedError {
     constructor(message?: string, response?: unknown);
 }
 /**
- * Error thrown when an OAuth operation fails.
- *
- * This can occur during authorization, token exchange, refresh, or revocation.
+ * Thrown by {@link OAuthResource} methods when authorization, token
+ * exchange, refresh, or revocation fails.
  *
  * @category Errors
  */
 declare class OAuthError extends VairifiedError {
-    /** OAuth error code (e.g., 'invalid_grant', 'expired_token') */
-    errorCode?: string;
+    /**
+     * OAuth error code such as `'invalid_grant'`, `'invalid_scope'`,
+     * or `'expired_token'`. Check this to branch on the specific failure.
+     */
+    readonly errorCode?: string;
     constructor(message?: string, errorCode?: string, response?: unknown);
 }
 
-export { AuthenticationError, type AuthorizationResponse, DEFAULT_SCOPES, Match, type MatchApiData, type MatchInput, MatchResult, type MatchResultData, Member, type MemberData, NotFoundError, type OAuthConfig, OAuthError, type OAuthScope, Player, type PlayerSearchData, RateLimitError, RatingSplit, type RatingSplitData, RatingSplits, type RatingSplitsData, RatingUpdate, type RatingUpdateData, SCOPES, type SearchFilters, SearchResults, type SearchResultsData, type TokenResponse, Vairified, type VairifiedEnvironment, VairifiedError, type VairifiedOptions, ValidationError, describeScope, describeScopes, generateState, getAuthorizationUrl, validateScope };
+export { type ApiErrorResponse, AuthenticationError, type AuthorizationResponse, DEFAULT_SCOPES, ENVIRONMENTS, type GameInput, type Gender, type LeaderboardOptions, LeaderboardResource, type MatchBatch, MatchBatchResult, type MatchBatchResultWire, type MatchInput, MatchesResource, Member, MemberSportMap, type MemberStatusWire, MembersResource, NotFoundError, type OAuthConfig, OAuthError, OAuthResource, type OAuthScope, type PartnerMemberWire, type PartnerRatingUpdateWire, type PlayerRankOptions, RateLimitError, type RatingSplitWire, RatingUpdate, SCOPES, type SearchFilters, SportRating, type SportRatingWire, type TokenResponse, Vairified, type VairifiedEnvironment, VairifiedError, type VairifiedOptions, ValidationError, describeScope, describeScopes, generateState, getAuthorizationUrl, validateScope };