vairified 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1015 @@
+/**
+ * Vairified SDK Types
+ *
+ * @module
+ */
+/**
+ * Options for initializing the Vairified client.
+ *
+ * @category Types
+ */
+interface VairifiedOptions {
+    /** API key for authentication */
+    apiKey?: string;
+    /** Environment preset: "production" (default), "staging", "local" */
+    env?: 'production' | 'staging' | 'local';
+    /** Override API base URL. Takes precedence over env. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+}
+/**
+ * A single rating split with metadata.
+ *
+ * @category Types
+ */
+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;
+}
+/**
+ * Rating splits from API - map of category to rating data.
+ *
+ * @category Types
+ */
+type RatingSplitsData = Record<string, RatingSplitData | number>;
+/**
+ * Player data from getMember endpoint (requires OAuth connection).
+ *
+ * @category Types
+ */
+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[];
+}
+/**
+ * Player data from search endpoint (public, limited data).
+ *
+ * @category Types
+ */
+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;
+}
+/**
+ * Filters for player search.
+ *
+ * @category Types
+ */
+interface SearchFilters {
+    /** Name search (partial match) */
+    name?: string;
+    /** City filter */
+    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) */
+    ratingMin?: number;
+    /** Maximum rating (2.0-8.0) */
+    ratingMax?: number;
+    /** Gender filter */
+    gender?: 'MALE' | 'FEMALE';
+    /** Only verified players */
+    vairifiedOnly?: boolean;
+    /** Exact age */
+    age?: number;
+    /** Minimum age */
+    ageMin?: number;
+    /** Maximum age */
+    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;
+}
+/**
+ * Match input for creating a Match.
+ *
+ * @category Types
+ */
+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;
+}
+/**
+ * Match data as sent to API.
+ *
+ * @category Types
+ */
+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;
+}
+
+/**
+ * Vairified SDK Models
+ *
+ * Rich model classes with methods for easy API interaction.
+ *
+ * @module
+ */
+
+/** Union type for player data from different endpoints */
+type PlayerData = MemberData | PlayerSearchData;
+/**
+ * A single rating split with metadata.
+ *
+ * @category Models
+ */
+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;
+}
+/**
+ * A member with full profile access (requires OAuth connection).
+ *
+ * Only accessible for players who have connected their account via OAuth.
+ *
+ * @category Models
+ */
+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>;
+}
+/**
+ * A match to submit to the Vairified Partner API.
+ *
+ * @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]],
+ * });
+ * ```
+ */
+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;
+}
+/**
+ * Result of a match submission.
+ *
+ * @category Models
+ */
+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;
+}
+/**
+ * A rating change notification.
+ *
+ * @category Models
+ */
+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 */
+    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>;
+}
+
+/**
+ * Vairified OAuth Helpers
+ *
+ * Utilities for implementing the "Connect with Vairified" OAuth flow.
+ *
+ * @module
+ */
+/**
+ * Available OAuth scopes with descriptions.
+ *
+ * @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";
+};
+/**
+ * Available OAuth scope keys.
+ *
+ * @category OAuth
+ */
+type OAuthScope = keyof typeof SCOPES;
+/**
+ * Default scopes requested for new connections.
+ *
+ * @category OAuth
+ */
+declare const DEFAULT_SCOPES: OAuthScope[];
+/**
+ * OAuth configuration for a partner application.
+ *
+ * @category OAuth
+ */
+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.
+ *
+ * @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;
+}
+/**
+ * Response from exchanging an authorization code for tokens.
+ *
+ * @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;
+}
+/**
+ * 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;
+ * ```
+ *
+ * @category OAuth
+ */
+declare function getAuthorizationUrl(config: OAuthConfig, scopes?: OAuthScope[], state?: string): string;
+/**
+ * Check if a scope is valid.
+ *
+ * @param scope - Scope string to validate
+ * @returns True if scope is valid
+ *
+ * @category OAuth
+ */
+declare function validateScope(scope: string): scope is OAuthScope;
+/**
+ * Get a human-readable description of a scope.
+ *
+ * @param scope - Scope string
+ * @returns Description of what the scope grants access to
+ *
+ * @category OAuth
+ */
+declare function describeScope(scope: OAuthScope): string;
+/**
+ * Get descriptions for multiple scopes.
+ *
+ * @param scopes - List of scope strings
+ * @returns Array of objects with scope and description
+ *
+ * @category OAuth
+ */
+declare function describeScopes(scopes: OAuthScope[]): Array<{
+    scope: OAuthScope;
+    description: string;
+}>;
+/**
+ * Generate a random state parameter for CSRF protection.
+ *
+ * @returns Random 32-character hexadecimal string
+ *
+ * @category OAuth
+ */
+declare function generateState(): string;
+
+/**
+ * Vairified SDK Client
+ *
+ * Main client for the Vairified Partner API.
+ *
+ * @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.
+ *
+ * @category Client
+ */
+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`);
+ * }
+ * ```
+ *
+ * @remarks
+ * If your API key has the "dry-run" scope, match submissions will be
+ * validated but not persisted. This is useful for testing integrations.
+ */
+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;
+    /**
+     * 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.
+     *
+     * @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
+     */
+    revokeConnection(playerId: string): Promise<void>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     *
+     * @category OAuth
+     */
+    getAvailableScopes(): Promise<Array<{
+        id: string;
+        name: string;
+        description: string;
+    }>>;
+    /**
+     * 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
+     */
+    getUsage(): Promise<Record<string, unknown>>;
+}
+
+/**
+ * Vairified SDK Errors
+ *
+ * @module
+ */
+/**
+ * Base error class for Vairified SDK errors.
+ *
+ * @category Errors
+ */
+declare class VairifiedError extends Error {
+    /** HTTP status code */
+    statusCode?: number;
+    /** Response body */
+    response?: unknown;
+    constructor(message: string, statusCode?: number, response?: unknown);
+}
+/**
+ * Error thrown when API rate limit is exceeded.
+ *
+ * @category Errors
+ */
+declare class RateLimitError extends VairifiedError {
+    /** Seconds to wait before retrying */
+    retryAfter?: number;
+    constructor(message?: string, retryAfter?: number, response?: unknown);
+}
+/**
+ * Error thrown when API key is invalid or missing.
+ *
+ * @category Errors
+ */
+declare class AuthenticationError extends VairifiedError {
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when a requested resource is not found.
+ *
+ * @category Errors
+ */
+declare class NotFoundError extends VairifiedError {
+    constructor(message?: string, response?: unknown);
+}
+/**
+ * Error thrown when request validation fails.
+ *
+ * @category Errors
+ */
+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.
+ *
+ * @category Errors
+ */
+declare class OAuthError extends VairifiedError {
+    /** OAuth error code (e.g., 'invalid_grant', 'expired_token') */
+    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 };