vairified 0.1.1 → 0.3.0

package/dist/index.d.cts

@@ -1,982 +1,1227 @@
 /**
- * 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
+ */
+/**
+ * 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.
+ *
+ * @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
  */
 /**
- * Options for initializing the Vairified client.
+ * Environment preset for the Vairified API.
  *
- * @category Types
+ * @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 Members
+ */
+type Gender = 'MALE' | 'FEMALE' | 'OTHER' | 'UNKNOWN';
+/**
+ * Raw rating split — one slice of a player's rating for a specific
+ * category × age bracket.
  *
- * @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;
+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 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 Types
+ * @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}.
+ *
+ * `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.
  *
- * @category Types
+ * 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 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;
+interface GameInput {
+    readonly scores: readonly number[];
+    readonly identifier?: string;
+    readonly winScore?: number;
+    readonly winBy?: number;
 }
 /**
- * Match data as sent to API.
+ * 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 Types
+ * @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 MatchInput {
+    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;
 }
-
 /**
- * Vairified SDK Models
+ * Compressed bulk match submission.
  *
- * Rich model classes with methods for easy API interaction.
+ * 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.
  *
- * @module
+ * @category Matches
  */
-
-/** Union type for player data from different endpoints */
-type PlayerData = MemberData | PlayerSearchData;
+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;
+}
 /**
- * A single rating split with metadata.
+ * Raw result from a batch submission.
  *
- * @category Models
+ * @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;
-    toString(): string;
+interface MatchBatchResultWire {
+    readonly success: boolean;
+    readonly numMatches: number;
+    readonly numGames: number;
+    readonly dryRun?: boolean;
+    readonly message?: string;
+    readonly errors?: readonly string[];
 }
 /**
- * A member with full profile access (requires OAuth connection).
+ * Filters for {@link LeaderboardResource.list}.
  *
- * Only accessible for players who have connected their account via OAuth.
- *
- * @category Models
+ * @category Leaderboards
  */
-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>;
+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;
 }
 /**
- * A match to submit to the Vairified Partner API.
+ * Options for {@link LeaderboardResource.rank}.
  *
- * @category Models
- *
- * @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]],
- * });
- * ```
+ * @category Leaderboards
  */
-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;
+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;
 }
 /**
- * Result of a match submission.
+ * Wire shape for tournament import response.
  *
- * @category Models
+ * @category Matches
  */
-declare class MatchResult {
-    /** Whether submission succeeded */
+interface TournamentImportResultWire {
     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 matchesImported: number;
+    readonly gamesRecorded: number;
+    readonly ghostPlayersCreated: number;
+    readonly existingPlayersMatched: number;
+    readonly dryRun?: boolean;
     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;
+    readonly errors?: readonly string[];
 }
 /**
- * A rating change notification.
+ * Wire shape for a single webhook delivery attempt.
  *
- * @category Models
+ * @category Webhooks
  */
-declare class RatingUpdate {
-    /** External player ID (vair_mem_xxx format) */
+interface WebhookDeliveryWire {
     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 */
-    get improved(): boolean;
-    /** Fetch the member associated with this update */
-    getMember(): Promise<Member>;
-    toString(): string;
+    readonly event: string;
+    readonly url: string;
+    readonly statusCode: number | null;
+    readonly responseBody: string | null;
+    readonly errorMessage: string | null;
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    readonly lastAttemptAt: string;
+    readonly nextRetryAt: string | null;
+    readonly completedAt: string | null;
+    readonly createdAt: string;
+    readonly payload: Record<string, unknown>;
 }
 /**
- * Paginated search results.
+ * Wire shape for paginated webhook delivery results.
  *
- * @category Models
+ * @category Webhooks
  */
-declare class SearchResults implements Iterable<Player> {
-    /** List of players */
-    readonly players: Player[];
-    /** Total matching players */
+interface WebhookDeliveriesResultWire {
+    readonly deliveries: readonly WebhookDeliveryWire[];
     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>;
 }
-
 /**
- * Vairified OAuth Helpers
+ * Error envelope commonly returned by the Partner API on non-2xx status.
  *
- * Utilities for implementing the "Connect with Vairified" OAuth flow.
+ * @category Errors
+ */
+interface ApiErrorResponse {
+    readonly message?: string;
+    readonly error?: string;
+    readonly statusCode?: number;
+}
+
+/**
+ * {@link LeaderboardResource} — read-only leaderboard queries.
  *
  * @module
  */
+
 /**
- * Available OAuth scopes with descriptions.
+ * Read-only leaderboard queries.
  *
- * @category OAuth
+ * @category Resources
  */
-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";
-};
+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>>;
+}
+
 /**
- * Available OAuth scope keys.
+ * {@link MatchBatchResult} — result of a batch match submission.
  *
- * @category OAuth
+ * @module
  */
-type OAuthScope = keyof typeof SCOPES;
+
 /**
- * Default scopes requested for new connections.
+ * Result of a {@link MatchesResource.submit} call.
  *
- * @category OAuth
+ * {@link success} is `true` only when every match in the batch was
+ * accepted. Check {@link errors} for per-match validation failures.
+ *
+ * @category Matches
  */
-declare const DEFAULT_SCOPES: OAuthScope[];
+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;
+}
+
 /**
- * OAuth configuration for a partner application.
+ * {@link TournamentImportResult} — result of a tournament import submission.
  *
- * @category OAuth
+ * @module
  */
-interface OAuthConfig {
-    /** Partner API key */
-    apiKey: string;
-    /** Your application's callback URL */
-    redirectUri: string;
-    /** Vairified API base URL */
-    baseUrl?: string;
-}
+
 /**
- * Response from starting an OAuth authorization.
+ * Result of a tournament import submission.
  *
- * @category OAuth
+ * @category Matches
  */
-interface AuthorizationResponse {
-    /** Full URL to redirect the user to */
-    authorizationUrl: string;
-    /** Authorization code (for internal tracking) */
-    code: string;
-    /** CSRF state parameter */
-    state?: string;
+declare class TournamentImportResult {
+    readonly success: boolean;
+    readonly matchesImported: number;
+    readonly gamesRecorded: number;
+    readonly ghostPlayersCreated: number;
+    readonly existingPlayersMatched: number;
+    readonly dryRun: boolean;
+    readonly message: string | undefined;
+    readonly errors: readonly string[];
+    /** @internal */
+    constructor(wire: TournamentImportResultWire);
+    /** True when the import succeeded without errors. */
+    get ok(): boolean;
 }
+
 /**
- * Response from exchanging an authorization code for tokens.
+ * {@link MatchesResource} — bulk match submission.
  *
- * @category OAuth
+ * @module
  */
-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;
+
+/**
+ * Match submission — one call submits a full batch.
+ *
+ * @category Resources
+ */
+declare class MatchesResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
+    /**
+     * Submit a {@link MatchBatch} for rating calculation.
+     *
+     * All players in every match must have granted the `user:match:submit`
+     * scope via OAuth (unless your API key has the
+     * `user: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>;
+    /**
+     * Import tournament results.
+     *
+     * The request body is a free-form JSON object whose structure is
+     * defined by the Vairified tournament import schema. Set
+     * `body.dryRun = true` to validate without persisting.
+     *
+     * @param body - Tournament import payload.
+     * @returns {@link TournamentImportResult} with match/game counts.
+     * @category Matches
+     *
+     * @example
+     * ```ts
+     * const result = await client.matches.tournamentImport({
+     *   sport: 'pickleball',
+     *   tournamentName: 'Spring Classic',
+     *   matches: [...],
+     * });
+     * if (result.ok) {
+     *   console.log(`Imported ${result.matchesImported} matches`);
+     * }
+     * ```
+     */
+    tournamentImport(body: Record<string, unknown>): Promise<TournamentImportResult>;
+    /** Send a test payload to a webhook URL. */
+    testWebhook(webhookUrl: string): Promise<Record<string, unknown>>;
 }
+
 /**
- * Build the URL to redirect users to for OAuth authorization.
+ * {@link SportRating} — a player's ratings for one sport.
  *
- * This is a helper for building the URL manually. In most cases,
- * you should use the Vairified client's OAuth methods instead.
+ * @module
+ */
+
+/**
+ * A player's ratings for a single sport.
  *
- * @param config - OAuth configuration
- * @param scopes - Permission scopes to request
- * @param state - CSRF protection state parameter
- * @returns URL to redirect the user to
+ * 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.
  *
- * @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;
+ * 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 OAuth
+ * @category Members
  */
-declare function getAuthorizationUrl(config: OAuthConfig, scopes?: OAuthScope[], state?: string): string;
+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]>;
+}
+
 /**
- * Check if a scope is valid.
- *
- * @param scope - Scope string to validate
- * @returns True if scope is valid
+ * {@link Member} — partner-facing player record.
  *
- * @category OAuth
+ * @module
  */
-declare function validateScope(scope: string): scope is OAuthScope;
+
 /**
- * Get a human-readable description of a scope.
+ * Map-like wrapper around a player's sport → {@link SportRating}.
  *
- * @param scope - Scope string
- * @returns Description of what the scope grants access to
+ * Supports `.get(code)`, `.has(code)`, `.size`, and iteration so the
+ * shape feels native:
  *
- * @category OAuth
+ * ```ts
+ * member.sport.get('pickleball')?.rating
+ * for (const [code, rating] of member.sport) { ... }
+ * ```
+ *
+ * @category Members
  */
-declare function describeScope(scope: OAuthScope): string;
+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]>;
+}
 /**
- * Get descriptions for multiple scopes.
+ * A partner-facing player record.
  *
- * @param scopes - List of scope strings
- * @returns Array of objects with scope and description
+ * Returned by {@link MembersResource.get} (full detail, requires an
+ * active OAuth connection) and {@link MembersResource.search} (limited
+ * detail for public search).
  *
- * @category OAuth
+ * 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 function describeScopes(scopes: OAuthScope[]): Array<{
-    scope: OAuthScope;
-    description: string;
-}>;
+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;
+}
+
 /**
- * Generate a random state parameter for CSRF protection.
- *
- * @returns Random 32-character hexadecimal string
+ * {@link RatingUpdate} — a single rating change notification.
  *
- * @category OAuth
+ * @module
  */
-declare function generateState(): string;
 
 /**
- * Vairified SDK Client
+ * A single rating change notification.
  *
- * Main client for the Vairified Partner API.
+ * Returned by {@link MembersResource.ratingUpdates} (polling) and
+ * delivered via webhook callbacks to partners that have registered a
+ * webhook URL and have subscribers.
  *
- * @module
+ * @category Members
  */
+declare class RatingUpdate {
+    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;
+    toString(): string;
+}
 
-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.
+ * {@link MembersResource} — member lookups, search, and rating updates.
  *
- * @category Client
+ * @module
  */
-type VairifiedEnvironment = keyof typeof ENVIRONMENTS;
+
 /**
- * Client for the Vairified Partner API.
- *
- * @category Client
- *
- * @example
- * ```ts
- * const client = new Vairified({ apiKey: 'vair_pk_xxx' });
- *
- * // Get a member
- * const member = await client.getMember('user_123');
- * console.log(member.name, member.rating);
- *
- * // Search for players
- * const results = await client.search({ city: 'Austin', ratingMin: 4.0 });
- * for (const player of results) {
- *   console.log(player.name, player.rating);
- * }
- *
- * // 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`);
- * }
- * ```
+ * Member operations — get a single member, auto-paginating search,
+ * find by name, and polling for rating change notifications.
  *
- * @remarks
- * If your API key has the "dry-run" scope, match submissions will be
- * validated but not persisted. This is useful for testing integrations.
+ * @category Resources
  */
-declare class Vairified {
-    /** API key */
-    readonly apiKey: string;
-    /** Base URL */
-    readonly baseUrl: string;
-    /** Environment name */
-    readonly env: VairifiedEnvironment;
-    /** Request timeout in ms */
-    readonly timeout: number;
-    constructor(options?: VairifiedOptions);
-    private getEnvVar;
-    private getEnvApiKey;
-    private getHeaders;
-    private handleError;
-    private request;
+declare class MembersResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
     /**
-     * Get a connected member by their external ID.
+     * Get a connected member by external ID.
      *
-     * **Requires OAuth Connection**: The player must have connected their
-     * account to your application via OAuth before you can access their data.
+     * **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 (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
+     * @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.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.
+     * const member = await client.members.get('vair_mem_xxx');
+     * console.log(member.name, member.ratingFor('pickleball'));
      *
-     * @param filters - Search filters
-     * @returns SearchResults with players and pagination
+     * // Just pickleball
+     * const member2 = await client.members.get('vair_mem_xxx', { sport: 'pickleball' });
      *
-     * @example
-     * ```ts
-     * const results = await client.search({
-     *   city: 'Austin',
-     *   ratingMin: 4.0,
-     *   vairifiedOnly: true,
+     * // Multiple sports
+     * const member3 = await client.members.get('vair_mem_xxx', {
+     *   sport: ['pickleball', 'padel'],
      * });
-     *
-     * 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>;
+    get(playerId: string, options?: {
+        sport?: string | readonly string[];
+    }): Promise<Member>;
     /**
-     * Find a single player by name.
+     * Search for members, yielding each match as a {@link Member}.
      *
-     * @param name - Player name to search for
-     * @returns Player if found, undefined otherwise
+     * 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:
      *
-     * @example
      * ```ts
-     * const player = await client.findPlayer('John Smith');
-     * if (player) {
-     *   console.log(player.rating);
+     * for await (const m of client.members.search({ city: 'Austin' })) {
+     *   console.log(m.name, m.ratingFor('pickleball'));
      * }
      * ```
-     */
-    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`);
-     * }
-     * ```
+     * Stop early by `break`-ing out of the loop, or cap the total with
+     * `maxResults`.
      */
-    submitMatch(match: Match): Promise<MatchResult>;
+    search(filters?: SearchFilters): AsyncGenerator<Member, void, void>;
     /**
-     * Submit multiple matches in a batch.
+     * Return the first search hit for a name, or `null`.
      *
-     * @param matches - List of Match objects
-     * @returns MatchResult with submission status
+     * Convenience for the common "look up by name" case:
      *
-     * @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');
+     * const mike = await client.members.find('Mike Barker');
+     * if (mike) {
+     *   console.log(mike.ratingFor('pickleball'));
      * }
      * ```
      */
-    submitMatches(matches: Match[]): Promise<MatchResult>;
+    find(name: string): Promise<Member | null>;
     /**
-     * Get rating updates for subscribed members.
+     * Fetch up to 100 members by their member IDs in one call.
      *
-     * Members are subscribed when you call getMember().
+     * Unknown IDs are silently omitted — the returned array may be
+     * shorter than the input. Results are returned in the same order
+     * as the input IDs.
      *
-     * @returns List of RatingUpdate objects
+     * @param ids - Array of integer member IDs (max 100).
+     * @param options - Optional filters.
+     * @param options.sport - Sport code to scope ratings (e.g. `'pickleball'`).
+     * @returns Array of {@link Member} instances.
+     * @throws {@link ValidationError} If more than 100 IDs are provided.
+     * @category Members
      *
      * @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!`);
-     *   }
+     * const members = await client.members.getBulk([4873327, 4873328]);
+     * for (const m of members) {
+     *   console.log(m.name, m.ratingFor('pickleball'));
      * }
      * ```
      */
-    getRatingUpdates(): Promise<RatingUpdate[]>;
+    getBulk(ids: number[], options?: {
+        sport?: string;
+    }): Promise<Member[]>;
     /**
-     * Test webhook endpoint.
+     * Poll for rating change notifications.
      *
-     * @param webhookUrl - URL to send test webhook to
-     * @returns Test result
+     * 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 `user:webhook:subscribe` scope.
      */
-    testWebhook(webhookUrl: string): Promise<Record<string, unknown>>;
+    ratingUpdates(): Promise<readonly RatingUpdate[]>;
+}
+
+/**
+ * Vairified OAuth helpers and type definitions.
+ *
+ * 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
+ */
+/**
+ * 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[] = ['user:profile:read', 'user:rating:read']; // ok
+ * const bad: OAuthScope[] = ['user:profile:read', 'rating']; // type error
+ * ```
+ *
+ * @category OAuth
+ */
+type OAuthScope = 'user:profile:read' | 'user:profile:email' | 'user:rating:read' | 'user:rating:history' | 'user:match:submit' | 'user:webhook:subscribe';
+/**
+ * Human-readable description for every OAuth scope.
+ *
+ * @category OAuth
+ */
+declare const SCOPES: Readonly<Record<OAuthScope, string>>;
+/**
+ * The scopes automatically requested when none are specified.
+ *
+ * @category OAuth
+ */
+declare const DEFAULT_SCOPES: readonly OAuthScope[];
+/**
+ * Configuration for building an authorization URL manually.
+ *
+ * @category OAuth
+ */
+interface OAuthConfig {
+    readonly apiKey: string;
+    readonly redirectUri: string;
+    readonly baseUrl?: string;
+}
+/**
+ * Response from starting an OAuth authorization flow.
+ *
+ * @category OAuth
+ */
+interface AuthorizationResponse {
+    readonly authorizationUrl: string;
+    readonly code: string;
+    readonly state?: string;
+}
+/**
+ * Response from exchanging an authorization code for tokens.
+ *
+ * @category OAuth
+ */
+interface TokenResponse {
+    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.
+ *
+ * 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, options?: {
+    scopes?: readonly OAuthScope[];
+    state?: string;
+}): string;
+/**
+ * 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 an OAuth scope.
+ *
+ * Returns `"Unknown scope: {scope}"` for unrecognized scopes so this
+ * function is safe to call on user-supplied input.
+ *
+ * @category OAuth
+ */
+declare function describeScope(scope: string): string;
+/**
+ * Describe multiple scopes at once.
+ *
+ * @category OAuth
+ */
+declare function describeScopes(scopes: readonly string[]): readonly {
+    scope: string;
+    description: string;
+}[];
+/**
+ * Generate a cryptographically-random CSRF state token suitable for
+ * use with {@link OAuthResource.authorize}.
+ *
+ * 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;
+
+/**
+ * {@link OAuthResource} — OAuth 2.0 flow for player consent.
+ *
+ * @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.
      *
-     * 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
+     * @throws {@link OAuthError} with `errorCode: 'invalid_scope'` if a
+     *   requested scope is not in the accepted list.
      */
-    exchangeToken(code: string, redirectUri: string): Promise<TokenResponse>;
+    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 WebhookDelivery} and {@link WebhookDeliveriesResult} — webhook
+ * delivery inspection models.
+ *
+ * @module
+ */
+
+/**
+ * A single webhook delivery attempt.
+ *
+ * @category Webhooks
+ */
+declare class WebhookDelivery {
+    readonly id: string;
+    readonly event: string;
+    readonly url: string;
+    readonly statusCode: number | null;
+    readonly responseBody: string | null;
+    readonly errorMessage: string | null;
+    readonly attempts: number;
+    readonly maxAttempts: number;
+    readonly lastAttemptAt: string;
+    readonly nextRetryAt: string | null;
+    readonly completedAt: string | null;
+    readonly createdAt: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+    /** @internal */
+    constructor(wire: WebhookDeliveryWire);
+    /** Whether delivery completed successfully (2xx status). */
+    get succeeded(): boolean;
+    /** Whether delivery failed definitively (completed with non-2xx). */
+    get failed(): boolean;
+}
+/**
+ * Paginated list of webhook delivery attempts.
+ *
+ * @category Webhooks
+ */
+declare class WebhookDeliveriesResult {
+    readonly deliveries: readonly WebhookDelivery[];
+    readonly total: number;
+    /** @internal */
+    constructor(wire: WebhookDeliveriesResultWire);
+}
+
+/**
+ * {@link WebhooksResource} — webhook delivery inspection.
+ *
+ * @module
+ */
+
+/**
+ * Webhook delivery inspection.
+ *
+ * @category Resources
+ */
+declare class WebhooksResource {
+    #private;
+    /** @internal */
+    constructor(http: HttpTransport);
     /**
-     * Refresh an expired access token.
-     *
-     * Use this when an access token expires to obtain a new one
-     * without requiring the user to re-authorize.
+     * List recent webhook delivery attempts.
      *
-     * @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
+     * @param options - Optional filters and pagination.
+     * @param options.event - Filter by event type (e.g. `'rating.updated'`).
+     * @param options.status - Filter: `'all'`, `'pending'`, `'success'`, or `'failed'`.
+     * @param options.limit - Results per page (1-100, default 20).
+     * @param options.offset - Pagination offset.
+     * @returns {@link WebhookDeliveriesResult} with entries and total.
+     * @category Webhooks
      *
      * @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
-     *   }
+     * const result = await client.webhooks.deliveries({ status: 'failed' });
+     * for (const d of result.deliveries) {
+     *   console.log(d.event, d.statusCode, d.errorMessage);
      * }
      * ```
-     *
-     * @category OAuth
      */
-    refreshAccessToken(refreshToken: string): Promise<TokenResponse>;
+    deliveries(options?: {
+        event?: string;
+        status?: 'all' | 'pending' | 'success' | 'failed';
+        limit?: number;
+        offset?: number;
+    }): Promise<WebhookDeliveriesResult>;
+}
+
+/**
+ * {@link Vairified} — the main entry point of the SDK.
+ *
+ * @module
+ */
+
+/**
+ * Environment preset → base URL mapping.
+ *
+ * Partners can switch between production, staging, and local development
+ * without memorizing hostnames.
+ *
+ * @category Client
+ */
+declare const ENVIRONMENTS: Readonly<Record<VairifiedEnvironment, string>>;
+/**
+ * Async client for the Vairified Partner API.
+ *
+ * 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.
+ *
+ * ## Lifecycle
+ *
+ * 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:
+ *
+ * ```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'));
+ *
+ * for await (const m of client.members.search({ city: 'Austin' })) {
+ *   console.log(m.name);
+ * }
+ * ```
+ *
+ * `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 {
+    #private;
+    /** The resolved API key this client is using. */
+    readonly apiKey: string;
+    /** The resolved base URL (production, staging, local, or custom). */
+    readonly baseUrl: string;
+    /** The resolved environment name. */
+    readonly env: VairifiedEnvironment;
+    /** 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;
+    /** Webhook delivery inspection — deliveries. */
+    readonly webhooks: WebhooksResource;
+    constructor(options?: VairifiedOptions);
     /**
-     * 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
-     *
-     * @example
-     * ```ts
-     * const scopes = await client.getAvailableScopes();
-     * for (const scope of scopes) {
-     *   console.log(`${scope.id}: ${scope.description}`);
-     * }
-     * ```
+     * Release any resources held by the client.
      *
-     * @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 +1229,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 +1237,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 +1247,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, TournamentImportResult, type TournamentImportResultWire, Vairified, type VairifiedEnvironment, VairifiedError, type VairifiedOptions, ValidationError, WebhookDeliveriesResult, type WebhookDeliveriesResultWire, WebhookDelivery, type WebhookDeliveryWire, WebhooksResource, describeScope, describeScopes, generateState, getAuthorizationUrl, validateScope };