vairified 0.2.0 → 0.3.1

package/README.md

@@ -50,13 +50,14 @@ exits. If you can't use it, call `await client.close()` manually.
 
 Every operation lives on a sub-resource that mirrors the REST path:
 
-| Sub-resource            | Operations                                                  |
-|-------------------------|-------------------------------------------------------------|
-| `client.members`        | `get`, `search`, `find`, `ratingUpdates`                    |
-| `client.matches`        | `submit`, `testWebhook`                                     |
-| `client.oauth`          | `authorize`, `exchangeToken`, `refresh`, `revoke`           |
-| `client.leaderboard`    | `list`, `rank`, `categories`                                |
-| `client.usage()`        | Rate-limit + request-count stats                            |
+| Sub-resource            | Operations                                                       |
+|-------------------------|------------------------------------------------------------------|
+| `client.members`        | `get`, `getBulk`, `search`, `find`, `ratingUpdates`              |
+| `client.matches`        | `submit`, `tournamentImport`, `testWebhook`                      |
+| `client.oauth`          | `authorize`, `exchangeToken`, `refresh`, `revoke`                |
+| `client.webhooks`       | `deliveries`                                                     |
+| `client.leaderboard`    | `list`, `rank`, `categories`                                     |
+| `client.usage()`        | Rate-limit + request-count stats                                 |
 
 ## Members
 
@@ -82,6 +83,22 @@ if (pb) {
 }
 ```
 
+### Bulk member lookup
+
+Fetch up to 100 members in one call by their integer member IDs:
+
+```ts
+const members = await client.members.getBulk([4873327, 4873328, 4873329]);
+for (const m of members) {
+  console.log(m.name, m.ratingFor('pickleball'));
+}
+
+// Filter to a specific sport
+const pb = await client.members.getBulk([4873327], { sport: 'pickleball' });
+```
+
+Unknown IDs are silently omitted — the returned array may be shorter than the input.
+
 ### Filter ratings to specific sports
 
 ```ts
@@ -172,8 +189,57 @@ if (result.ok) {
 }
 ```
 
-Set `dryRun: true` on the batch to validate without persisting — your API key must have
-the `dry-run` scope.
+Set `dryRun: true` on the batch to validate without persisting. No special scope
+needed — any key with `key:match:submit` can dry-run.
+
+### Tournament import
+
+Import historical tournament results with automatic player matching. Unmatched players
+become ghost accounts that can be claimed later.
+
+```ts
+const result = await client.matches.tournamentImport({
+  tournamentName: 'Austin Open 2026',
+  sport: 'pickleball',
+  winScore: 11,
+  winBy: 2,
+  matches: [
+    {
+      identifier: 'USAP-R1-M1',
+      event: 'Austin Open',
+      bracket: "Men's Pro Doubles",
+      format: 'DOUBLES',
+      matchDate: '2026-04-11T10:00:00Z',
+      teamA: {
+        player1: { firstName: 'Ben', lastName: 'Johns' },
+        player2: { firstName: 'Matt', lastName: 'Wright' },
+        game1: 11, game2: 11,
+      },
+      teamB: {
+        player1: { firstName: 'JW', lastName: 'Johnson' },
+        player2: { firstName: 'Dylan', lastName: 'Frazier' },
+        game1: 7, game2: 9,
+      },
+    },
+  ],
+});
+console.log(`Imported ${result.matchesImported} matches, ${result.ghostPlayersCreated} ghosts`);
+```
+
+## Webhook Deliveries
+
+Inspect recent webhook delivery attempts for your app:
+
+```ts
+const result = await client.webhooks.deliveries({ status: 'failed', limit: 10 });
+for (const d of result.deliveries) {
+  console.log(d.event, d.statusCode, d.errorMessage);
+}
+
+// Filter by event type
+const ratingEvents = await client.webhooks.deliveries({ event: 'rating.updated' });
+console.log(`${ratingEvents.total} total rating.updated deliveries`);
+```
 
 ## OAuth Connect Flow
 
@@ -186,7 +252,7 @@ await using client = new Vairified({ apiKey: 'vair_pk_xxx' });
 const state = generateState();
 const auth = await client.oauth.authorize({
   redirectUri: 'https://myapp.com/oauth/callback',
-  scopes: ['profile:read', 'rating:read', 'match:submit'],
+  scopes: ['user:profile:read', 'user:rating:read', 'user:match:submit'],
   state,
 });
 // Redirect user to auth.authorizationUrl
@@ -216,20 +282,20 @@ await client.oauth.revoke(playerId);
 ```ts
 import type { OAuthScope } from 'vairified';
 
-const scopes: OAuthScope[] = ['profile:read', 'rating:read']; // ok
-const bad: OAuthScope[] = ['profile:read', 'rating']; // type error
+const scopes: OAuthScope[] = ['user:profile:read', 'user:rating:read']; // ok
+const bad: OAuthScope[] = ['user:profile:read', 'rating']; // type error
 ```
 
 ### Available scopes
 
-| Scope                | Description                                    |
-|----------------------|------------------------------------------------|
-| `profile:read`       | Name, location, verification status            |
-| `profile:email`      | Email address                                  |
-| `rating:read`        | Current rating and rating splits               |
-| `rating:history`     | Complete rating history                        |
-| `match:submit`       | Submit matches on behalf of user               |
-| `webhook:subscribe`  | Rating change notifications                    |
+| Scope                     | Description                                    |
+|---------------------------|------------------------------------------------|
+| `user:profile:read`       | Name, location, verification status            |
+| `user:profile:email`      | Email address                                  |
+| `user:rating:read`        | Current rating and rating splits               |
+| `user:rating:history`     | Complete rating history                        |
+| `user:match:submit`       | Submit matches on behalf of user               |
+| `user:webhook:subscribe`  | Rating change notifications                    |
 
 ## Leaderboards
 
@@ -364,9 +430,13 @@ pb?.has('singles-40+')  // Membership check
 for (const [key, split] of pb ?? []) { /* iterate */ }
 ```
 
-## Migrating from 0.1.x
+## Migrating
+
+**From 0.2.x → 0.3.0:** All OAuth scope strings gained a `user:` prefix
+(`profile:read` → `user:profile:read`). Update any hardcoded scope arrays.
+New: `members.getBulk()`, `matches.tournamentImport()`, `webhooks.deliveries()`.
 
-Version 0.2.0 is a breaking rewrite. See the
+**From 0.1.x → 0.2.0:** Full rewrite. See the
 [migration guide](https://vairified.github.io/vairified.js/documents/Migrating_from_0.1.x.html)
 for the full diff and [CHANGELOG.md](CHANGELOG.md) for the release notes.
 

package/dist/index.cjs

@@ -36,9 +36,13 @@ __export(index_exports, {
   RatingUpdate: () => RatingUpdate,
   SCOPES: () => SCOPES,
   SportRating: () => SportRating,
+  TournamentImportResult: () => TournamentImportResult,
   Vairified: () => Vairified,
   VairifiedError: () => VairifiedError,
   ValidationError: () => ValidationError,
+  WebhookDeliveriesResult: () => WebhookDeliveriesResult,
+  WebhookDelivery: () => WebhookDelivery,
+  WebhooksResource: () => WebhooksResource,
   describeScope: () => describeScope,
   describeScopes: () => describeScopes,
   generateState: () => generateState,
@@ -293,6 +297,34 @@ var MatchBatchResult = class {
   }
 };
 
+// src/models/tournament-import-result.ts
+var TournamentImportResult = class {
+  success;
+  matchesImported;
+  gamesRecorded;
+  ghostPlayersCreated;
+  existingPlayersMatched;
+  dryRun;
+  message;
+  errors;
+  /** @internal */
+  constructor(wire) {
+    this.success = wire.success;
+    this.matchesImported = wire.matchesImported;
+    this.gamesRecorded = wire.gamesRecorded;
+    this.ghostPlayersCreated = wire.ghostPlayersCreated;
+    this.existingPlayersMatched = wire.existingPlayersMatched;
+    this.dryRun = wire.dryRun ?? false;
+    this.message = wire.message;
+    this.errors = Object.freeze(wire.errors ?? []);
+    Object.freeze(this);
+  }
+  /** True when the import succeeded without errors. */
+  get ok() {
+    return this.success && this.errors.length === 0;
+  }
+};
+
 // src/resources/matches.ts
 var MatchesResource = class {
   #http;
@@ -303,9 +335,9 @@ var MatchesResource = class {
   /**
    * Submit a {@link MatchBatch} for rating calculation.
    *
-   * All players in every match must have granted the `match:submit`
+   * All players in every match must have granted the `user:match:submit`
    * scope via OAuth (unless your API key has the
-   * `match:submit:trusted` scope, which skips per-player consent).
+   * `user:match:submit:trusted` scope, which skips per-player consent).
    *
    * Set `batch.dryRun = true` to validate without persisting.
    *
@@ -339,6 +371,37 @@ var MatchesResource = class {
     });
     return new MatchBatchResult(wire);
   }
+  /**
+   * 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`);
+   * }
+   * ```
+   */
+  async tournamentImport(body) {
+    const wire = await this.#http.request({
+      method: "POST",
+      path: "/partner/tournament-import",
+      body
+    });
+    return new TournamentImportResult(wire);
+  }
   /** Send a test payload to a webhook URL. */
   async testWebhook(webhookUrl) {
     const data = await this.#http.request({
@@ -663,13 +726,48 @@ var MembersResource = class {
     }
     return null;
   }
+  /**
+   * Fetch up to 100 members by their member IDs in one call.
+   *
+   * 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.
+   *
+   * @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 members = await client.members.getBulk([4873327, 4873328]);
+   * for (const m of members) {
+   *   console.log(m.name, m.ratingFor('pickleball'));
+   * }
+   * ```
+   */
+  async getBulk(ids, options) {
+    if (ids.length > 100) {
+      throw new ValidationError("Maximum 100 member IDs per request");
+    }
+    const query = { ids: ids.join(",") };
+    if (options?.sport) query.sport = options.sport;
+    const rows = await this.#http.request({
+      method: "GET",
+      path: "/partner/members",
+      query
+    });
+    return rows.map((row) => new Member(row));
+  }
   /**
    * Poll for rating change notifications.
    *
    * Returns a list of {@link RatingUpdate} objects for every player
    * whose rating has changed since the last poll. Members are
    * considered subscribed when they have an active OAuth connection
-   * with the `webhook:subscribe` scope.
+   * with the `user:webhook:subscribe` scope.
    */
   async ratingUpdates() {
     const data = await this.#http.request({
@@ -732,14 +830,17 @@ function resolveAgeFilter(filters) {
 
 // src/oauth.ts
 var SCOPES = Object.freeze({
-  "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"
+  "user:profile:read": "Access your name, location, and verification status",
+  "user:profile:email": "Access your email address",
+  "user:rating:read": "View your current rating and rating splits",
+  "user:rating:history": "View your complete rating history",
+  "user:match:submit": "Submit match results on your behalf",
+  "user:webhook:subscribe": "Receive notifications when your rating changes"
 });
-var DEFAULT_SCOPES = Object.freeze(["profile:read", "rating:read"]);
+var DEFAULT_SCOPES = Object.freeze([
+  "user:profile:read",
+  "user:rating:read"
+]);
 function getAuthorizationUrl(config, options = {}) {
   const baseUrl = (config.baseUrl ?? "https://api-next.vairified.com/api/v1").replace(/\/+$/, "");
   const scopeList = ensureProfileRead(options.scopes ?? DEFAULT_SCOPES);
@@ -778,10 +879,10 @@ function generateState() {
   return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 function ensureProfileRead(scopes) {
-  if (scopes.includes("profile:read")) {
+  if (scopes.includes("user:profile:read")) {
     return scopes;
   }
-  return ["profile:read", ...scopes];
+  return ["user:profile:read", ...scopes];
 }
 
 // src/resources/oauth.ts
@@ -870,6 +971,99 @@ function tokenResponseFromWire(data) {
   };
 }
 
+// src/models/webhook-delivery.ts
+var WebhookDelivery = class {
+  id;
+  event;
+  url;
+  statusCode;
+  responseBody;
+  errorMessage;
+  attempts;
+  maxAttempts;
+  lastAttemptAt;
+  nextRetryAt;
+  completedAt;
+  createdAt;
+  payload;
+  /** @internal */
+  constructor(wire) {
+    this.id = wire.id;
+    this.event = wire.event;
+    this.url = wire.url;
+    this.statusCode = wire.statusCode;
+    this.responseBody = wire.responseBody;
+    this.errorMessage = wire.errorMessage;
+    this.attempts = wire.attempts;
+    this.maxAttempts = wire.maxAttempts;
+    this.lastAttemptAt = wire.lastAttemptAt;
+    this.nextRetryAt = wire.nextRetryAt;
+    this.completedAt = wire.completedAt;
+    this.createdAt = wire.createdAt;
+    this.payload = Object.freeze({ ...wire.payload });
+    Object.freeze(this);
+  }
+  /** Whether delivery completed successfully (2xx status). */
+  get succeeded() {
+    return this.completedAt != null && this.statusCode != null && this.statusCode >= 200 && this.statusCode < 300;
+  }
+  /** Whether delivery failed definitively (completed with non-2xx). */
+  get failed() {
+    return this.completedAt != null && !this.succeeded;
+  }
+};
+var WebhookDeliveriesResult = class {
+  deliveries;
+  total;
+  /** @internal */
+  constructor(wire) {
+    this.deliveries = Object.freeze(wire.deliveries.map((d) => new WebhookDelivery(d)));
+    this.total = wire.total;
+    Object.freeze(this);
+  }
+};
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  #http;
+  /** @internal */
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * List recent webhook delivery attempts.
+   *
+   * @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
+   * const result = await client.webhooks.deliveries({ status: 'failed' });
+   * for (const d of result.deliveries) {
+   *   console.log(d.event, d.statusCode, d.errorMessage);
+   * }
+   * ```
+   */
+  async deliveries(options) {
+    const query = {};
+    if (options?.event) query.event = options.event;
+    if (options?.status) query.status = options.status;
+    if (options?.limit != null) query.limit = options.limit;
+    if (options?.offset != null) query.offset = options.offset;
+    const data = await this.#http.request({
+      method: "GET",
+      path: "/partner/webhook-deliveries",
+      query
+    });
+    return new WebhookDeliveriesResult(data);
+  }
+};
+
 // src/client.ts
 var ENVIRONMENTS = Object.freeze({
   production: "https://api-next.vairified.com/api/v1",
@@ -894,6 +1088,8 @@ var Vairified = class {
   oauth;
   /** Leaderboard queries — list, rank, categories. */
   leaderboard;
+  /** Webhook delivery inspection — deliveries. */
+  webhooks;
   #transport;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env.VAIRIFIED_API_KEY ?? "";
@@ -925,6 +1121,7 @@ var Vairified = class {
     this.matches = new MatchesResource(this.#transport);
     this.oauth = new OAuthResource(this.#transport);
     this.leaderboard = new LeaderboardResource(this.#transport);
+    this.webhooks = new WebhooksResource(this.#transport);
   }
   /**
    * API usage statistics for the current API key.
@@ -977,9 +1174,13 @@ var Vairified = class {
   RatingUpdate,
   SCOPES,
   SportRating,
+  TournamentImportResult,
   Vairified,
   VairifiedError,
   ValidationError,
+  WebhookDeliveriesResult,
+  WebhookDelivery,
+  WebhooksResource,
   describeScope,
   describeScopes,
   generateState,