vairified 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1042 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  DEFAULT_SCOPES: () => DEFAULT_SCOPES,
+  Match: () => Match,
+  MatchResult: () => MatchResult,
+  Member: () => Member,
+  NotFoundError: () => NotFoundError,
+  OAuthError: () => OAuthError,
+  Player: () => Player,
+  RateLimitError: () => RateLimitError,
+  RatingSplit: () => RatingSplit,
+  RatingSplits: () => RatingSplits,
+  RatingUpdate: () => RatingUpdate,
+  SCOPES: () => SCOPES,
+  SearchResults: () => SearchResults,
+  Vairified: () => Vairified,
+  VairifiedError: () => VairifiedError,
+  ValidationError: () => ValidationError,
+  describeScope: () => describeScope,
+  describeScopes: () => describeScopes,
+  generateState: () => generateState,
+  getAuthorizationUrl: () => getAuthorizationUrl,
+  validateScope: () => validateScope
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var VairifiedError = class extends Error {
+  /** HTTP status code */
+  statusCode;
+  /** Response body */
+  response;
+  constructor(message, statusCode, response) {
+    super(message);
+    this.name = "VairifiedError";
+    this.statusCode = statusCode;
+    this.response = response;
+  }
+};
+var RateLimitError = class extends VairifiedError {
+  /** Seconds to wait before retrying */
+  retryAfter;
+  constructor(message = "Rate limit exceeded", retryAfter, response) {
+    super(message, 429, response);
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+  }
+};
+var AuthenticationError = class extends VairifiedError {
+  constructor(message = "Invalid API key", response) {
+    super(message, 401, response);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends VairifiedError {
+  constructor(message = "Resource not found", response) {
+    super(message, 404, response);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends VairifiedError {
+  constructor(message = "Validation error", response) {
+    super(message, 400, response);
+    this.name = "ValidationError";
+  }
+};
+var OAuthError = class extends VairifiedError {
+  /** OAuth error code (e.g., 'invalid_grant', 'expired_token') */
+  errorCode;
+  constructor(message = "OAuth error", errorCode, response) {
+    super(message, void 0, response);
+    this.name = "OAuthError";
+    this.errorCode = errorCode;
+  }
+};
+
+// src/models.ts
+var RatingSplit = class {
+  /** The rating value */
+  rating;
+  /** Abbreviation (e.g., "VG", "50+") */
+  abbr;
+  /** Date of last match in this category */
+  datePlayed;
+  constructor(data) {
+    if (typeof data === "number") {
+      this.rating = data;
+      this.abbr = "";
+    } else {
+      const ratingVal = data.rating;
+      this.rating = typeof ratingVal === "string" ? Number.parseFloat(ratingVal) || 0 : ratingVal;
+      this.abbr = data.abbr;
+      this.datePlayed = data.date_played;
+    }
+  }
+};
+var RatingSplits = class {
+  /** Map of category names to rating splits */
+  splits;
+  constructor(data) {
+    this.splits = /* @__PURE__ */ new Map();
+    if (data) {
+      for (const [key, value] of Object.entries(data)) {
+        this.splits.set(key, new RatingSplit(value));
+      }
+    }
+  }
+  /** Get rating for a category */
+  get(category) {
+    return this.splits.get(category)?.rating;
+  }
+  /** Open division rating */
+  get open() {
+    return this.get("open") ?? this.get("VO");
+  }
+  /** Gender-specific rating (same gender doubles) */
+  get gender() {
+    return this.get("gender") ?? this.get("VG");
+  }
+  /** Mixed doubles rating */
+  get mixed() {
+    return this.get("mixed") ?? this.get("VM");
+  }
+  /** Recreational rating */
+  get recreational() {
+    return this.get("recreational") ?? this.get("R");
+  }
+  /** Singles rating */
+  get singles() {
+    return this.get("singles") ?? this.get("S");
+  }
+  /** Best available verified rating */
+  get best() {
+    const ratings = Array.from(this.splits.values()).map((s) => s.rating).filter((r) => r > 0);
+    return ratings.length > 0 ? Math.max(...ratings) : void 0;
+  }
+  /** Convert to plain object */
+  toJSON() {
+    const result = {};
+    for (const [key, split] of this.splits) {
+      result[key] = { rating: split.rating, abbr: split.abbr };
+    }
+    return result;
+  }
+};
+function isSearchData(data) {
+  return "displayName" in data;
+}
+var Player = class {
+  /** External player ID (vair_mem_xxx format) */
+  id;
+  /** Display name (First Name + Last Initial from search) */
+  displayName;
+  /** First name (only from connected member) */
+  firstName;
+  /** Last name (only from connected member) */
+  lastName;
+  /** Primary/overall rating (2.0-8.0) */
+  rating;
+  /** Whether player is verified */
+  isVairified;
+  /** Whether player has connected to your app */
+  isConnected;
+  /** Ratings by category (only from connected member) */
+  ratingSplits;
+  /** City */
+  city;
+  /** State code */
+  state;
+  /** Country code */
+  country;
+  _client;
+  constructor(data, client) {
+    if (isSearchData(data)) {
+      this.id = data.id;
+      this.displayName = data.displayName;
+      this.rating = data.rating ?? 0;
+      this.isVairified = data.isVairified ?? false;
+      this.isConnected = data.isConnected ?? false;
+      this.ratingSplits = new RatingSplits();
+    } else {
+      this.id = data.id;
+      this.firstName = data.firstName ?? "";
+      this.lastName = data.lastName ?? "";
+      this.rating = data.rating ?? 0;
+      this.isVairified = data.isVairified ?? false;
+      this.isConnected = true;
+      this.ratingSplits = new RatingSplits(data.ratingSplits);
+    }
+    this.city = data.city;
+    this.state = data.state;
+    this.country = data.country;
+    this._client = client;
+  }
+  /** Full name (or display name if full name not available) */
+  get name() {
+    if (this.firstName && this.lastName) {
+      return `${this.firstName} ${this.lastName}`.trim();
+    }
+    return this.displayName ?? "";
+  }
+  /** Best verified rating */
+  get verifiedRating() {
+    return this.ratingSplits.best;
+  }
+  toString() {
+    const verified = this.isVairified ? " \u2713" : "";
+    return `${this.name} (${this.rating.toFixed(2)})${verified}`;
+  }
+};
+var Member = class extends Player {
+  /** Email address (only if profile:email scope granted) */
+  email;
+  /** Scopes the player granted to your app */
+  grantedScopes;
+  constructor(data, client) {
+    super(data, client);
+    this.email = data.email;
+    this.grantedScopes = data.grantedScopes ?? [];
+  }
+  /** Check if the player has granted a specific scope */
+  hasScope(scope) {
+    return this.grantedScopes.includes(scope);
+  }
+  /** Refresh member data from API */
+  async refresh() {
+    if (!this._client) {
+      throw new Error("Member not connected to client");
+    }
+    const updated = await this._client.getMember(this.id);
+    Object.assign(this, updated);
+    return this;
+  }
+};
+function generateId() {
+  return `SDK-${Math.random().toString(36).substring(2, 14)}`;
+}
+var Match = class {
+  /** Event/tournament name */
+  event;
+  /** Bracket/division name */
+  bracket;
+  /** Match date */
+  date;
+  /** Team 1 player IDs */
+  team1;
+  /** Team 2 player IDs */
+  team2;
+  /** Game scores */
+  scores;
+  /** Match type */
+  matchType;
+  /** Match source */
+  source;
+  /** Location */
+  location;
+  /** Unique identifier */
+  identifier;
+  /** Match ID (set after submission) */
+  id;
+  constructor(data) {
+    this.event = data.event;
+    this.bracket = data.bracket;
+    this.date = data.date instanceof Date ? data.date : new Date(data.date);
+    this.team1 = data.team1;
+    this.team2 = data.team2;
+    this.scores = data.scores;
+    this.matchType = data.matchType ?? "SIDEOUT";
+    this.source = data.source ?? "PARTNER";
+    this.location = data.location;
+    this.identifier = data.identifier ?? generateId();
+  }
+  /** Match format: SINGLES or DOUBLES */
+  get format() {
+    return this.team1.length === 1 ? "SINGLES" : "DOUBLES";
+  }
+  /** Team that won (1 or 2). Returns 0 if tie. */
+  get winner() {
+    let t1Wins = 0;
+    let t2Wins = 0;
+    for (const [s1, s2] of this.scores) {
+      if (s1 > s2) t1Wins++;
+      else if (s2 > s1) t2Wins++;
+    }
+    if (t1Wins > t2Wins) return 1;
+    if (t2Wins > t1Wins) return 2;
+    return 0;
+  }
+  /** Score summary like "11-9, 11-7" */
+  get scoreSummary() {
+    return this.scores.map(([s1, s2]) => `${s1}-${s2}`).join(", ");
+  }
+  /** Convert to API request format */
+  toJSON() {
+    const player1A = this.team1[0];
+    const player1B = this.team2[0];
+    if (!player1A || !player1B) {
+      throw new Error("Match must have at least one player per team");
+    }
+    const teamA = { player1: player1A };
+    const teamB = { player1: player1B };
+    if (this.team1[1]) teamA.player2 = this.team1[1];
+    if (this.team2[1]) teamB.player2 = this.team2[1];
+    const gameKeys = ["game1", "game2", "game3", "game4", "game5"];
+    for (let i = 0; i < Math.min(this.scores.length, 5); i++) {
+      const score = this.scores[i];
+      const key = gameKeys[i];
+      if (score && key) {
+        teamA[key] = score[0];
+        teamB[key] = score[1];
+      }
+    }
+    return {
+      identifier: this.identifier,
+      bracket: this.bracket,
+      event: this.event,
+      format: this.format,
+      matchDate: this.date.toISOString(),
+      matchSource: this.source,
+      matchType: this.matchType,
+      location: this.location,
+      teamA,
+      teamB
+    };
+  }
+};
+var MatchResult = class {
+  /** Whether submission succeeded */
+  success;
+  /** Number of matches processed */
+  numMatches;
+  /** Number of games recorded */
+  numGames;
+  /** Whether this was a dry-run (validation only) */
+  dryRun;
+  /** Human-readable result message */
+  message;
+  /** List of validation/processing errors */
+  errors;
+  constructor(data) {
+    this.success = data.success;
+    this.numMatches = data.numMatches;
+    this.numGames = data.numGames;
+    this.dryRun = data.dryRun ?? false;
+    this.message = data.message;
+    this.errors = data.errors ?? [];
+  }
+  /** Alias for dryRun */
+  get isDryRun() {
+    return this.dryRun;
+  }
+  /** Returns true if submission succeeded without errors */
+  get ok() {
+    return this.success && this.errors.length === 0;
+  }
+};
+var RatingUpdate = class {
+  /** External player ID (vair_mem_xxx format) */
+  id;
+  /** Member name */
+  memberName;
+  /** Previous rating */
+  previousRating;
+  /** New rating */
+  newRating;
+  /** When the change occurred */
+  changedAt;
+  /** Updated rating splits */
+  ratingSplits;
+  _client;
+  constructor(data, client) {
+    this.id = data.id;
+    this.memberName = data.memberName;
+    this.previousRating = data.previousRating ?? 0;
+    this.newRating = data.newRating ?? 0;
+    this.changedAt = data.changedAt ? new Date(data.changedAt) : /* @__PURE__ */ new Date();
+    this.ratingSplits = new RatingSplits(data.ratingSplits);
+    this._client = client;
+  }
+  /** Amount of rating change */
+  get change() {
+    return this.newRating - this.previousRating;
+  }
+  /** Whether rating improved */
+  get improved() {
+    return this.change > 0;
+  }
+  /** Fetch the member associated with this update */
+  async getMember() {
+    if (!this._client) {
+      throw new Error("Update not connected to client");
+    }
+    return this._client.getMember(this.id);
+  }
+  toString() {
+    const direction = this.improved ? "\u2191" : "\u2193";
+    const name = this.memberName ? ` (${this.memberName})` : "";
+    return `${this.id}${name}: ${this.previousRating.toFixed(2)} ${direction} ${this.newRating.toFixed(2)}`;
+  }
+};
+var SearchResults = class {
+  /** List of players */
+  players;
+  /** Total matching players */
+  total;
+  /** Current page */
+  page;
+  /** Results per page */
+  limit;
+  _client;
+  _filters;
+  constructor(data, client, filters = {}) {
+    this.players = data.players.map((p) => new Player(p, client));
+    this.total = data.total;
+    this.page = data.page;
+    this.limit = data.limit;
+    this._client = client;
+    this._filters = filters;
+  }
+  /** Whether more results are available */
+  get hasMore() {
+    return this.page * this.limit < this.total;
+  }
+  /** Total number of pages */
+  get pages() {
+    return this.limit > 0 ? Math.ceil(this.total / this.limit) : 0;
+  }
+  /** Number of players in current page */
+  get length() {
+    return this.players.length;
+  }
+  /** Get player by index */
+  at(index) {
+    return this.players[index];
+  }
+  /** Iterate over players */
+  [Symbol.iterator]() {
+    return this.players[Symbol.iterator]();
+  }
+  /** Fetch next page of results */
+  async nextPage() {
+    if (!this._client) {
+      throw new Error("Results not connected to client");
+    }
+    if (!this.hasMore) {
+      throw new Error("No more pages");
+    }
+    return this._client.search({
+      ...this._filters,
+      page: this.page + 1
+    });
+  }
+};
+
+// src/oauth.ts
+var SCOPES = {
+  "profile:read": "Access your name, location, and verification status",
+  "profile:email": "Access your email address",
+  "rating:read": "View your current rating and rating splits",
+  "rating:history": "View your complete rating history",
+  "match:submit": "Submit match results on your behalf",
+  "webhook:subscribe": "Receive notifications when your rating changes"
+};
+var DEFAULT_SCOPES = ["profile:read", "rating:read"];
+function getAuthorizationUrl(config, scopes = DEFAULT_SCOPES, state) {
+  const baseUrl = config.baseUrl || "https://api-next.vairified.com/api/v1";
+  const scopeSet = new Set(scopes);
+  scopeSet.add("profile:read");
+  const scopeList = Array.from(scopeSet);
+  const params = new URLSearchParams({
+    redirect_uri: config.redirectUri,
+    scope: scopeList.join(","),
+    response_type: "code"
+  });
+  if (state) {
+    params.set("state", state);
+  }
+  return `${baseUrl}/partner/oauth/authorize?${params.toString()}`;
+}
+function validateScope(scope) {
+  return scope in SCOPES;
+}
+function describeScope(scope) {
+  return SCOPES[scope] ?? `Unknown scope: ${scope}`;
+}
+function describeScopes(scopes) {
+  return scopes.map((scope) => ({
+    scope,
+    description: describeScope(scope)
+  }));
+}
+function generateState() {
+  const array = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+    crypto.getRandomValues(array);
+  } else {
+    for (let i = 0; i < array.length; i++) {
+      array[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  return Array.from(array).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// src/client.ts
+var ENVIRONMENTS = {
+  production: "https://api-next.vairified.com/api/v1",
+  staging: "https://api-staging.vairified.com/api/v1",
+  local: "http://localhost:3001/api/v1"
+};
+var DEFAULT_BASE_URL = ENVIRONMENTS.production;
+var DEFAULT_TIMEOUT = 3e4;
+var Vairified = class {
+  /** API key */
+  apiKey;
+  /** Base URL */
+  baseUrl;
+  /** Environment name */
+  env;
+  /** Request timeout in ms */
+  timeout;
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || this.getEnvApiKey();
+    if (!this.apiKey) {
+      throw new Error("API key required. Pass apiKey option or set VAIRIFIED_API_KEY env var.");
+    }
+    if (options.baseUrl) {
+      this.baseUrl = options.baseUrl.replace(/\/$/, "");
+      this.env = "production";
+    } else if (options.env) {
+      this.baseUrl = ENVIRONMENTS[options.env];
+      this.env = options.env;
+    } else {
+      const envVar = this.getEnvVar("VAIRIFIED_ENV");
+      const defaultEnv = envVar && envVar in ENVIRONMENTS ? envVar : "production";
+      this.baseUrl = ENVIRONMENTS[defaultEnv] || DEFAULT_BASE_URL;
+      this.env = defaultEnv;
+    }
+    this.timeout = options.timeout || DEFAULT_TIMEOUT;
+  }
+  getEnvVar(name) {
+    if (typeof process !== "undefined" && process.env?.[name]) {
+      return process.env[name];
+    }
+    return "";
+  }
+  getEnvApiKey() {
+    return this.getEnvVar("VAIRIFIED_API_KEY");
+  }
+  getHeaders() {
+    return {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+  }
+  async handleError(response) {
+    let body;
+    let message;
+    try {
+      body = await response.json();
+      message = body.message || response.statusText;
+    } catch {
+      message = response.statusText;
+    }
+    const status = response.status;
+    if (status === 401) throw new AuthenticationError(message, body);
+    if (status === 404) throw new NotFoundError(message, body);
+    if (status === 429) {
+      const retryAfter = response.headers.get("Retry-After");
+      throw new RateLimitError(
+        message,
+        retryAfter ? Number.parseInt(retryAfter, 10) : void 0,
+        body
+      );
+    }
+    if (status === 400) throw new ValidationError(message, body);
+    throw new VairifiedError(message, status, body);
+  }
+  async request(method, path, options) {
+    let url = `${this.baseUrl}${path}`;
+    if (options?.params) {
+      const searchParams = new URLSearchParams();
+      for (const [key, value] of Object.entries(options.params)) {
+        if (value !== void 0 && value !== null) {
+          searchParams.append(key, String(value));
+        }
+      }
+      const queryString = searchParams.toString();
+      if (queryString) url += `?${queryString}`;
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: this.getHeaders(),
+        body: options?.body ? JSON.stringify(options.body) : void 0,
+        signal: controller.signal
+      });
+      if (!response.ok) await this.handleError(response);
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Member Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * 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']
+   * ```
+   */
+  async getMember(playerId) {
+    const data = await this.request("GET", "/partner/member", {
+      params: { id: playerId }
+    });
+    return new Member(data, this);
+  }
+  // ---------------------------------------------------------------------------
+  // Search Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * 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();
+   * }
+   * ```
+   */
+  async search(filters = {}) {
+    const params = {
+      limit: filters.limit ?? 20
+    };
+    if (filters.name) params.member = filters.name;
+    if (filters.city) params.city = filters.city;
+    if (filters.state) params.state = filters.state;
+    if (filters.country) params.country = filters.country;
+    if (filters.zipCode) params.zip = filters.zipCode;
+    if (filters.ratingMin !== void 0) params.rating1 = filters.ratingMin;
+    if (filters.ratingMax !== void 0) params.rating2 = filters.ratingMax;
+    if (filters.gender) params.gender = filters.gender;
+    if (filters.vairifiedOnly) params.vairified = true;
+    if (filters.sortBy) {
+      params.sortField = filters.sortBy;
+      params.sortDirection = filters.sortOrder ?? "desc";
+    }
+    if (filters.age !== void 0) {
+      params.ageFilterType = "exact";
+      params.age1 = filters.age;
+    } else if (filters.ageMin !== void 0 && filters.ageMax !== void 0) {
+      params.ageFilterType = "range";
+      params.age1 = filters.ageMin;
+      params.age2 = filters.ageMax;
+    } else if (filters.ageMin !== void 0) {
+      params.ageFilterType = "above";
+      params.age1 = filters.ageMin;
+    } else if (filters.ageMax !== void 0) {
+      params.ageFilterType = "below";
+      params.age1 = filters.ageMax;
+    }
+    const page = filters.page ?? 1;
+    if (page > 1) {
+      params.offset = (page - 1) * (filters.limit ?? 20);
+    }
+    const data = await this.request(
+      "GET",
+      "/partner/search",
+      {
+        params
+      }
+    );
+    const normalized = Array.isArray(data) ? { players: data, total: data.length, page, limit: filters.limit ?? 20 } : data;
+    return new SearchResults(normalized, this, filters);
+  }
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async findPlayer(name) {
+    const results = await this.search({ name, limit: 1 });
+    return results.at(0);
+  }
+  // ---------------------------------------------------------------------------
+  // Match Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * 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`);
+   * }
+   * ```
+   */
+  async submitMatch(match) {
+    return this.submitMatches([match]);
+  }
+  /**
+   * 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');
+   * }
+   * ```
+   */
+  async submitMatches(matches) {
+    const data = await this.request("POST", "/partner/matches", {
+      body: { matches: matches.map((m) => m.toJSON()) }
+    });
+    return new MatchResult(data);
+  }
+  // ---------------------------------------------------------------------------
+  // Rating Updates
+  // ---------------------------------------------------------------------------
+  /**
+   * 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!`);
+   *   }
+   * }
+   * ```
+   */
+  async getRatingUpdates() {
+    const data = await this.request(
+      "GET",
+      "/partner/rating-updates"
+    );
+    return (data.updates ?? []).map((u) => new RatingUpdate(u, this));
+  }
+  /**
+   * Test webhook endpoint.
+   *
+   * @param webhookUrl - URL to send test webhook to
+   * @returns Test result
+   */
+  async testWebhook(webhookUrl) {
+    return this.request("POST", "/partner/webhook-test", {
+      body: { webhookUrl }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // OAuth Operations
+  // ---------------------------------------------------------------------------
+  /**
+   * 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
+   */
+  async startOAuth(redirectUri, scopes = [...DEFAULT_SCOPES], state) {
+    const scopeSet = new Set(scopes);
+    scopeSet.add("profile:read");
+    const scopeList = Array.from(scopeSet);
+    for (const scope of scopeList) {
+      if (!(scope in SCOPES)) {
+        throw new OAuthError(`Invalid scope: ${scope}`, "invalid_scope");
+      }
+    }
+    const data = await this.request("POST", "/partner/oauth/authorize", {
+      body: {
+        redirectUri,
+        scope: scopeList.join(","),
+        state
+      }
+    });
+    return {
+      authorizationUrl: data.authorizationUrl,
+      code: data.code,
+      state
+    };
+  }
+  /**
+   * 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
+   */
+  async exchangeToken(code, redirectUri) {
+    const data = await this.request("POST", "/partner/oauth/token", {
+      body: { code, redirectUri }
+    });
+    return {
+      accessToken: data.accessToken,
+      refreshToken: data.refreshToken,
+      expiresIn: data.expiresIn,
+      scope: data.scope ? data.scope.split(",") : [],
+      playerId: data.playerId
+    };
+  }
+  /**
+   * 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
+   */
+  async refreshAccessToken(refreshToken) {
+    const data = await this.request("POST", "/partner/oauth/refresh", {
+      body: { refreshToken }
+    });
+    return {
+      accessToken: data.accessToken,
+      refreshToken: data.refreshToken,
+      expiresIn: data.expiresIn,
+      scope: data.scope ? data.scope.split(",") : [],
+      playerId: data.playerId
+    };
+  }
+  /**
+   * 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
+   */
+  async revokeConnection(playerId) {
+    await this.request("POST", "/partner/oauth/revoke", {
+      body: { playerId }
+    });
+  }
+  /**
+   * 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
+   */
+  async getAvailableScopes() {
+    const data = await this.request("GET", "/partner/oauth/scopes");
+    return data.scopes ?? [];
+  }
+  /**
+   * 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
+   */
+  async getUsage() {
+    return this.request("GET", "/partner/usage");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  DEFAULT_SCOPES,
+  Match,
+  MatchResult,
+  Member,
+  NotFoundError,
+  OAuthError,
+  Player,
+  RateLimitError,
+  RatingSplit,
+  RatingSplits,
+  RatingUpdate,
+  SCOPES,
+  SearchResults,
+  Vairified,
+  VairifiedError,
+  ValidationError,
+  describeScope,
+  describeScopes,
+  generateState,
+  getAuthorizationUrl,
+  validateScope
+});
+//# sourceMappingURL=index.cjs.map